ה-API של Checks Guardrails זמין עכשיו בגרסת אלפא בתצוגה מקדימה פרטית. כדי לבקש גישה לגרסת Private Preview, צריך למלא את טופס ההתעניינות שלנו.
Guardrails API הוא API שמאפשר לבדוק אם הטקסט עלול להיות מזיק או לא בטוח. אתם יכולים להשתמש ב-API הזה באפליקציית ה-AI הגנרטיבי שלכם כדי למנוע מהמשתמשים להיחשף לתוכן שעלול להזיק.
איך משתמשים בשכבות הגנה?
אתם יכולים להשתמש באמצעי ההגנה של Checks כדי לזהות ולצמצם את הסיכון להופעת טקסט שמפר את המדיניות שלכם בקלט ובפלט של ה-AI הגנרטיבי.
למה כדאי להשתמש באמצעי בקרה?
לפעמים מודלים מסוג LLM יכולים ליצור תוכן שעלול להיות מזיק או לא הולם. שילוב של Guardrails API באפליקציית ה-GenAI שלכם הוא חיוני כדי להבטיח שימוש אחראי ובטוח יותר במודלים גדולים של שפה (LLM). הוא עוזר לצמצם את הסיכונים שקשורים לתוכן שנוצר על ידי AI, על ידי סינון מגוון רחב של פלטים שעלולים להיות מזיקים, כולל שפה לא הולמת, הערות מפלות ותוכן שיכול להקל על גרימת נזק. השימוש ב-SSV לא רק מגן על המשתמשים, אלא גם שומר על המוניטין של האפליקציה ומחזק את האמון בקרב הקהל. הגדרת אמצעי הבטיחות מאפשרת לכם לתת עדיפות לבטיחות ולאחריות, ולפתח אפליקציות AI גנרטיביות שהן גם חדשניות וגם בטוחות יותר.
תחילת העבודה
במדריך הזה מוסבר איך להשתמש ב-Guardrails API כדי לזהות ולסנן תוכן לא הולם באפליקציות. ה-API מציע מגוון של כללי מדיניות שאומנו מראש ויכולים לזהות סוגים שונים של תוכן שעלול להיות מזיק, כמו דברי שטנה, אלימות ותוכן מיני בוטה. אפשר גם להתאים אישית את אופן הפעולה של ה-API על ידי הגדרת ספי ערכים לכל כלל מדיניות.
דרישות מוקדמות
- הפרויקט שלכם ב-Google Cloud אושר להשתתפות בגרסת הטרום-השקה הפרטית של Checks AI Safety. אם עדיין לא עשיתם זאת, אתם יכולים לבקש גישה באמצעות הטופס לציון התעניינות.
- מפעילים את Checks API.
- חשוב לוודא שאתם יכולים לשלוח בקשות מורשות באמצעות מדריך ההרשאה שלנו.
כללי מדיניות נתמכים
שם מדיניות | תיאור המדיניות | הערך של הטיפוס בן המנייה (enum) של Policy Type API |
---|---|---|
תוכן מסוכן | תוכן שמסייע לפעילויות מזיקות או מקדם אותן, או שמאפשר גישה למוצרים ושירותים מזיקים. | DANGEROUS_CONTENT |
בקשת פרטים אישיים מזהים (PII) וציטוט שלהם | תוכן שמבקש או חושף מידע אישי רגיש או נתונים של אדם מסוים. | PII_SOLICITING_RECITING |
הטרדה | תוכן זדוני, מאיים, בריוני או פוגעני כלפי אדם או אנשים אחרים. | HARASSMENT |
תוכן מיני בוטה | תוכן בעל אופי מיני בוטה. | SEXUALLY_EXPLICIT |
דברי שטנה | תוכן שמקובל בדרך כלל כדברי שטנה. | HATE_SPEECH |
מידע רפואי | אסור לפרסם תוכן שמאפשר גישה להנחיות או לעצות רפואיות מזיקות, מקדם אותן או עוזר להשיג אותן. | MEDICAL_INFO |
אלימות ופציעות קשות | תוכן שכולל תיאורים מפורטים של אלימות ריאליסטית ו/או שפיכות דמים. | VIOLENCE_AND_GORE |
שפה מגונה או גסה | אסור לפרסם תוכן שכולל שפה גסה, מגונה או פוגענית. | OBSCENITY_AND_PROFANITY |
קטעי קוד
Python
מריצים את הפקודה pip install
google-api-python-client
כדי להתקין את לקוח Google API Python.
import logging
from google.oauth2 import service_account
from googleapiclient.discovery import build
SECRET_FILE_PATH = 'path/to/your/secret.json'
credentials = service_account.Credentials.from_service_account_file(
SECRET_FILE_PATH, scopes=['https://www.googleapis.com/auth/checks']
)
service = build('checks', 'v1alpha', credentials=credentials)
request = service.aisafety().classifyContent(
body={
'input': {
'textInput': {
'content': 'Mix, bake, cool, frost, and enjoy.',
'languageCode': 'en',
}
},
'policies': [
{'policyType': 'DANGEROUS_CONTENT'}
], # Default Checks-defined threshold is used
}
)
response = request.execute()
for policy_result in response['policyResults']:
logging.warning(
'Policy: %s, Score: %s, Violation result: %s',
policy_result['policyType'],
policy_result['score'],
policy_result['violationResult'],
)
Go
מריצים את הפקודה go get google.golang.org/api/checks/v1alpha
כדי להתקין את Checks API Go Client.
package main
import (
"context"
"log/slog"
checks "google.golang.org/api/checks/v1alpha"
option "google.golang.org/api/option"
)
const credsFilePath = "path/to/your/secret.json"
func main() {
ctx := context.Background()
checksService, err := checks.NewService(
ctx,
option.WithEndpoint("https://checks.googleapis.com"),
option.WithCredentialsFile(credsFilePath),
option.WithScopes("https://www.googleapis.com/auth/checks"),
)
if err != nil {
// Handle error
}
req := &checks.GoogleChecksAisafetyV1alphaClassifyContentRequest{
Input: &checks.GoogleChecksAisafetyV1alphaClassifyContentRequestInputContent{
TextInput: &checks.GoogleChecksAisafetyV1alphaTextInput{
Content: "Mix, bake, cool, frost, and enjoy.",
LanguageCode: "en",
},
},
Policies: []*checks.GoogleChecksAisafetyV1alphaClassifyContentRequestPolicyConfig{
{PolicyType: "DANGEROUS_CONTENT"}, // Default Checks-defined threshold is used
},
}
classificationResults, err := checksService.Aisafety.ClassifyContent(req).Do()
if err != nil {
// Handle error
}
for _, policy := range classificationResults.PolicyResults {
slog.Info("Checks Guardrails violation: ", "Policy", policy.PolicyType, "Score", policy.Score, "Violation Result", policy.ViolationResult)
}
}
REST
הערה: בדוגמה הזו נעשה שימוש בoauth2l
כלי CLI.
מחליפים את YOUR_GCP_PROJECT_ID
במזהה הפרויקט ב-Google Cloud שקיבל גישה ל-Guardrails API.
curl -X POST https://checks.googleapis.com/v1alpha/aisafety:classifyContent \
-H "$(oauth2l header --scope cloud-platform,checks)" \
-H "X-Goog-User-Project: YOUR_GCP_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"input": {
"text_input": {
"content": "Mix, bake, cool, frost, and enjoy.",
"language_code": "en"
}
},
"policies": [
{
"policy_type": "HARASSMENT",
"threshold": "0.5"
},
{
"policy_type": "DANGEROUS_CONTENT",
},
]
}'
דוגמה לתשובה
{
"policyResults": [
{
"policyType": "HARASSMENT",
"score": 0.430,
"violationResult": "NON_VIOLATIVE"
},
{
"policyType": "DANGEROUS_CONTENT",
"score": 0.764,
"violationResult": "VIOLATIVE"
},
{
"policyType": "OBSCENITY_AND_PROFANITY",
"score": 0.876,
"violationResult": "VIOLATIVE"
},
{
"policyType": "SEXUALLY_EXPLICIT",
"score": 0.197,
"violationResult": "NON_VIOLATIVE"
},
{
"policyType": "HATE_SPEECH",
"score": 0.45,
"violationResult": "NON_VIOLATIVE"
},
{
"policyType": "MEDICAL_INFO",
"score": 0.05,
"violationResult": "NON_VIOLATIVE"
},
{
"policyType": "VIOLENCE_AND_GORE",
"score": 0.964,
"violationResult": "VIOLATIVE"
},
{
"policyType": "PII_SOLICITING_RECITING",
"score": 0.0009,
"violationResult": "NON_VIOLATIVE"
}
]
}
תרחישים לדוגמה
יש מגוון דרכים לשלב את Guardrails API באפליקציית ה-LLM שלכם, בהתאם לצרכים הספציפיים ולמוכנות שלכם לקחת סיכונים. הנה כמה דוגמאות לתרחישי שימוש נפוצים:
No Guardrail Intervention - Logging
בתרחיש הזה, נעשה שימוש ב-Guardrails API ללא שינויים בהתנהגות האפליקציה. עם זאת, הפרות מדיניות אפשריות מתועדות לצורך מעקב וביקורת. אפשר להשתמש במידע הזה כדי לזהות סיכוני בטיחות פוטנציאליים של מודלים גדולים של שפה (LLM).
Python
import logging
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Checks API configuration
class ChecksConfig:
def __init__(self, scope, creds_file_path):
self.scope = scope
self.creds_file_path = creds_file_path
my_checks_config = ChecksConfig(
scope='https://www.googleapis.com/auth/checks',
creds_file_path='path/to/your/secret.json',
)
def new_checks_service(config):
"""Creates a new Checks API service."""
credentials = service_account.Credentials.from_service_account_file(
config.creds_file_path, scopes=[config.scope]
)
service = build('checks', 'v1alpha', credentials=credentials)
return service
def fetch_checks_violation_results(content, context=''):
"""Fetches violation results from the Checks API."""
service = new_checks_service(my_checks_config)
request = service.aisafety().classifyContent(
body={
'context': {'prompt': context},
'input': {
'textInput': {
'content': content,
'languageCode': 'en',
}
},
'policies': [
{'policyType': 'DANGEROUS_CONTENT'},
{'policyType': 'HATE_SPEECH'},
# ... add more policies
],
}
)
response = request.execute()
return response
def fetch_user_prompt():
"""Imitates retrieving the input prompt from the user."""
return 'How do I bake a cake?'
def fetch_llm_response(prompt):
"""Imitates the call to an LLM endpoint."""
return 'Mix, bake, cool, frost, enjoy.'
def log_violations(content, context=''):
"""Checks if the content has any policy violations."""
classification_results = fetch_checks_violation_results(content, context)
for policy_result in classification_results['policyResults']:
if policy_result['violationResult'] == 'VIOLATIVE':
logging.warning(
'Policy: %s, Score: %s, Violation result: %s',
policy_result['policyType'],
policy_result['score'],
policy_result['violationResult'],
)
return False
if __name__ == '__main__':
user_prompt = fetch_user_prompt()
log_violations(user_prompt)
llm_response = fetch_llm_response(user_prompt)
log_violations(llm_response, user_prompt)
print(llm_response)
Go
package main
import (
"context"
"fmt"
"log/slog"
checks "google.golang.org/api/checks/v1alpha"
option "google.golang.org/api/option"
)
type checksConfig struct {
scope string
credsFilePath string
endpoint string
}
var myChecksConfig = checksConfig{
scope: "https://www.googleapis.com/auth/checks",
credsFilePath: "path/to/your/secret.json",
endpoint: "https://checks.googleapis.com",
}
func newChecksService(ctx context.Context, cfg checksConfig) (*checks.Service, error) {
return checks.NewService(
ctx,
option.WithEndpoint(cfg.endpoint),
option.WithCredentialsFile(cfg.credsFilePath),
option.WithScopes(cfg.scope),
)
}
func fetchChecksViolationResults(ctx context.Context, content string, context string) (*checks.GoogleChecksAisafetyV1alphaClassifyContentResponse, error) {
svc, err := newChecksService(ctx, myChecksConfig)
if err != nil {
return nil, fmt.Errorf("failed to create checks service: %w", err)
}
req := &checks.GoogleChecksAisafetyV1alphaClassifyContentRequest{
Context: &checks.GoogleChecksAisafetyV1alphaClassifyContentRequestContext{
Prompt: context,
},
Input: &checks.GoogleChecksAisafetyV1alphaClassifyContentRequestInputContent{
TextInput: &checks.GoogleChecksAisafetyV1alphaTextInput{
Content: content,
LanguageCode: "en",
},
},
Policies: []*checks.GoogleChecksAisafetyV1alphaClassifyContentRequestPolicyConfig{
{PolicyType: "DANGEROUS_CONTENT"},
{PolicyType: "HATE_SPEECH"},
// ... add more policies
},
}
response, err := svc.Aisafety.ClassifyContent(req).Do()
if err != nil {
return nil, fmt.Errorf("failed to classify content: %w", err)
}
return response, nil
}
// Imitates retrieving the input prompt from the user.
func fetchUserPrompt() string {
return "How do I bake a cake?"
}
// Imitates the call to an LLM endpoint.
func fetchLLMResponse(prompt string) string {
return "Mix, bake, cool, frost, enjoy."
}
func logViolations(ctx context.Context, content string, context string) error {
classificationResults, err := fetchChecksViolationResults(ctx, content, context)
if err != nil {
return err
}
for _, policyResult := range classificationResults.PolicyResults {
if policyResult.ViolationResult == "VIOLATIVE" {
slog.Warn("Checks Guardrails violation: ", "Policy", policyResult.PolicyType, "Score", policyResult.Score, "Violation Result", policyResult.ViolationResult)
}
}
return nil
}
func main() {
ctx := context.Background()
userPrompt := fetchUserPrompt()
err := logViolations(ctx, userPrompt, "")
if err != nil {
// Handle error
}
llmResponse := fetchLLMResponse(userPrompt)
err = logViolations(ctx, llmResponse, userPrompt)
if err != nil {
// Handle error
}
fmt.Println(llmResponse)
}
הגבלת השימוש נחסמה על סמך מדיניות
בדוגמה הזו, Guardrails API חוסם קלט לא בטוח של משתמשים ותגובות של מודלים. הוא בודק את שניהם בהשוואה למדיניות בטיחות מוגדרת מראש (למשל, דברי שטנה, תוכן מסוכן). כך אנחנו מונעים מה-AI ליצור פלט שעלול להיות מזיק ומגנים על המשתמשים מפני תוכן לא הולם.
Python
from google.oauth2 import service_account
from googleapiclient.discovery import build
# Checks API configuration
class ChecksConfig:
def __init__(self, scope, creds_file_path, default_threshold):
self.scope = scope
self.creds_file_path = creds_file_path
self.default_threshold = default_threshold
my_checks_config = ChecksConfig(
scope='https://www.googleapis.com/auth/checks',
creds_file_path='path/to/your/secret.json',
default_threshold=0.6,
)
def new_checks_service(config):
"""Creates a new Checks API service."""
credentials = service_account.Credentials.from_service_account_file(
config.creds_file_path, scopes=[config.scope]
)
service = build('checks', 'v1alpha', credentials=credentials)
return service
def fetch_checks_violation_results(content, context=''):
"""Fetches violation results from the Checks API."""
service = new_checks_service(my_checks_config)
request = service.aisafety().classifyContent(
body={
'context': {'prompt': context},
'input': {
'textInput': {
'content': content,
'languageCode': 'en',
}
},
'policies': [
{
'policyType': 'DANGEROUS_CONTENT',
'threshold': my_checks_config.default_threshold,
},
{'policyType': 'HATE_SPEECH'},
# ... add more policies
],
}
)
response = request.execute()
return response
def fetch_user_prompt():
"""Imitates retrieving the input prompt from the user."""
return 'How do I bake a cake?'
def fetch_llm_response(prompt):
"""Imitates the call to an LLM endpoint."""
return 'Mix, bake, cool, frost, enjoy.'
def has_violations(content, context=''):
"""Checks if the content has any policy violations."""
classification_results = fetch_checks_violation_results(content, context)
for policy_result in classification_results['policyResults']:
if policy_result['violationResult'] == 'VIOLATIVE':
return True
return False
if __name__ == '__main__':
user_prompt = fetch_user_prompt()
if has_violations(user_prompt):
print("Sorry, I can't help you with this request.")
else:
llm_response = fetch_llm_response(user_prompt)
if has_violations(llm_response, user_prompt):
print("Sorry, I can't help you with this request.")
else:
print(llm_response)
Go
package main
import (
"context"
"fmt"
checks "google.golang.org/api/checks/v1alpha"
option "google.golang.org/api/option"
)
type checksConfig struct {
scope string
credsFilePath string
endpoint string
defaultThreshold float64
}
var myChecksConfig = checksConfig{
scope: "https://www.googleapis.com/auth/checks",
credsFilePath: "path/to/your/secret.json",
endpoint: "https://checks.googleapis.com",
defaultThreshold: 0.6,
}
func newChecksService(ctx context.Context, cfg checksConfig) (*checks.Service, error) {
return checks.NewService(
ctx,
option.WithEndpoint(cfg.endpoint),
option.WithCredentialsFile(cfg.credsFilePath),
option.WithScopes(cfg.scope),
)
}
func fetchChecksViolationResults(ctx context.Context, content string, context string) (*checks.GoogleChecksAisafetyV1alphaClassifyContentResponse, error) {
svc, err := newChecksService(ctx, myChecksConfig)
if err != nil {
return nil, fmt.Errorf("failed to create checks service: %w", err)
}
req := &checks.GoogleChecksAisafetyV1alphaClassifyContentRequest{
Context: &checks.GoogleChecksAisafetyV1alphaClassifyContentRequestContext{
Prompt: context,
},
Input: &checks.GoogleChecksAisafetyV1alphaClassifyContentRequestInputContent{
TextInput: &checks.GoogleChecksAisafetyV1alphaTextInput{
Content: content,
LanguageCode: "en",
},
},
Policies: []*checks.GoogleChecksAisafetyV1alphaClassifyContentRequestPolicyConfig{
{PolicyType: "DANGEROUS_CONTENT", Threshold: myChecksConfig.defaultThreshold},
{PolicyType: "HATE_SPEECH"}, // default Checks-defined threshold is used
// ... add more policies
},
}
response, err := svc.Aisafety.ClassifyContent(req).Do()
if err != nil {
return nil, fmt.Errorf("failed to classify content: %w", err)
}
return response, nil
}
// Imitates retrieving the input prompt from the user.
func fetchUserPrompt() string {
return "How do I bake a cake?"
}
// Imitates the call to an LLM endpoint.
func fetchLLMResponse(prompt string) string {
return "Mix, bake, cool, frost, enjoy."
}
func hasViolations(ctx context.Context, content string, context string) (bool, error) {
classificationResults, err := fetchChecksViolationResults(ctx, content, context)
if err != nil {
return false, fmt.Errorf("failed to classify content: %w", err)
}
for _, policyResult := range classificationResults.PolicyResults {
if policyResult.ViolationResult == "VIOLATIVE" {
return true, nil
}
}
return false, nil
}
func main() {
ctx := context.Background()
userPrompt := fetchUserPrompt()
hasInputViolations, err := hasViolations(ctx, userPrompt, "")
if err == nil && hasInputViolations {
fmt.Println("Sorry, I can't help you with this request.")
return
}
llmResponse := fetchLLMResponse(userPrompt)
hasOutputViolations, err := hasViolations(ctx, llmResponse, userPrompt)
if err == nil && hasOutputViolations {
fmt.Println("Sorry, I can't help you with this request.")
return
}
fmt.Println(llmResponse)
}
שידור פלט של מודל שפה גדול (LLM) למנגנון Guardrails
בדוגמאות הבאות, אנחנו מעבירים פלט מ-LLM ל-Guardrails API. אפשר להשתמש בזה כדי לקצר את זמן הטעינה הנתפס של המשתמשים. הגישה הזו עלולה להוביל לתוצאות חיוביות שגויות בגלל הקשר לא מלא, ולכן חשוב שלפלט של ה-LLM יהיה מספיק הקשר כדי שהמנגנון להגנה על נתונים יוכל לבצע הערכה מדויקת לפני הפעלת ה-API.
קריאות סינכרוניות של שכבות הגנה
Python
if __name__ == '__main__':
user_prompt = fetch_user_prompt()
my_llm_model = MockModel(
user_prompt, fetch_llm_response(user_prompt)
)
llm_response = ""
chunk = ""
# Minimum number of LLM chunks needed before we will call Guardrails.
contextThreshold = 2
while not my_llm_model.finished:
chunk = my_llm_model.next_chunk()
llm_response += str(chunk)
if my_llm_model.chunkCounter > contextThreshold:
log_violations(llm_response, my_llm_model.userPrompt)
Go
func main() {
ctx := context.Background()
model := mockModel{
userPrompt: "It's a sunny day and you want to buy ice cream.",
response: []string{"What a lovely day", "to get some ice cream.", "is the shop open?"},
}
// Minimum number of LLM chunks needed before we will call Guardrails.
const contextThreshold = 2
var llmResponse string
for !model.finished {
chunk := model.nextChunk()
llmResponse += chunk + " "
if model.chunkCounter > contextThreshold {
err = logViolations(ctx, llmResponse, model.userPrompt)
if err != nil {
// Handle error
}
}
}
}
הפעלות אסינכרוניות של שכבות הגנה
Python
async def main():
user_prompt = fetch_user_prompt()
my_llm_model = MockModel(
user_prompt, fetch_llm_response(user_prompt)
)
llm_response = ""
chunk = ""
# Minimum number of LLM chunks needed before we will call Guardrails.
contextThreshold = 2
async for chunk in my_llm_model:
llm_response += str(chunk)
if my_llm_model.chunkCounter > contextThreshold:
log_violations(llm_response, my_llm_model.userPrompt)
asyncio.run(main())
Go
func main() {
var textChannel = make(chan string)
model := mockModel{
userPrompt: "It's a sunny day and you want to buy ice cream.",
response: []string{"What a lovely day", "to get some ice cream.", "is the shop open?"},
}
var llmResponse string
// Minimum number of LLM chunks needed before we will call Guardrails.
const contextThreshold = 2
go model.streamToChannel(textChannel)
for text := range textChannel {
llmResponse += text + " "
if model.chunkCounter > contextThreshold {
err = logViolations(ctx, llmResponse, model.userPrompt)
if err != nil {
// Handle error
}
}
}
}
שאלות נפוצות
מה צריך לעשות אם מגיעים למגבלות המכסה של Guardrails API?
כדי לבקש הגדלה של המכסות, שולחים בקשה באימייל לכתובת checks-support@google.com. צריך לכלול באימייל את הפרטים הבאים:
- מספר הפרויקט שלכם ב-Google Cloud: כך נוכל לזהות במהירות את החשבון שלכם.
- פרטים על תרחיש השימוש: הסבר על אופן השימוש ב-Guardrails API.
- כמות המכסה הרצויה: מציינים כמה מכסה נוספת אתם צריכים.