Checks Guardrails API اکنون در نسخه آلفا در پیش نمایش خصوصی موجود است. با استفاده از فرم علاقه ما، درخواست دسترسی به پیش‌نمایش خصوصی کنید.
Guardrails API یک API است که به شما امکان می دهد بررسی کنید که آیا متن به طور بالقوه مضر است یا ناامن. می توانید از این API در برنامه GenAI خود استفاده کنید تا از قرار گرفتن کاربران در معرض محتوای بالقوه مضر جلوگیری کنید.
چگونه از گاردریل استفاده کنیم؟
برای شناسایی و کاهش وجود متنی که خط‌مشی‌های شما را نقض می‌کند، از Checks Guardrails در ورودی‌ها و خروجی‌های Gen AI خود استفاده کنید.
چرا از گاردریل استفاده کنیم؟
LLM ها گاهی اوقات می توانند محتوای بالقوه مضر یا نامناسب تولید کنند. ادغام API Guardrails در برنامه GenAI شما برای اطمینان از استفاده مسئولانه و ایمن‌تر از مدل‌های زبان بزرگ (LLM) بسیار مهم است. این به شما کمک می کند تا با فیلتر کردن طیف گسترده ای از خروجی های بالقوه مضر، از جمله زبان نامناسب، اظهارات تبعیض آمیز، و محتوایی که می تواند آسیب را تسهیل کند، خطرات مرتبط با محتوای تولید شده را کاهش دهید. این نه تنها از کاربران شما محافظت می کند، بلکه از اعتبار برنامه شما نیز محافظت می کند و اعتماد مخاطبان شما را تقویت می کند. با اولویت دادن به ایمنی و مسئولیت، Guardrails شما را قادر می سازد تا برنامه های GenAI را بسازید که هم نوآورانه و هم ایمن تر هستند.
شروع کردن
این راهنما دستورالعمل هایی برای استفاده از Guardrails API برای شناسایی و فیلتر کردن محتوای نامناسب در برنامه های شما ارائه می دهد. API خط‌مشی‌های از پیش آموزش‌دیده‌ای را ارائه می‌کند که می‌تواند انواع مختلفی از محتوای بالقوه مضر، مانند سخنان مشوق عداوت و تنفر، خشونت، و مطالب صریح جنسی را شناسایی کند. همچنین می توانید با تعیین آستانه برای هر خط مشی، رفتار API را سفارشی کنید.
پیش نیازها
- پروژه Google Cloud خود را برای پیش‌نمایش خصوصی Checks AI Safety تأیید کنید. اگر قبلاً این کار را نکرده‌اید، با استفاده از فرم علاقه ما درخواست دسترسی کنید.
- Checks API را فعال کنید.
- مطمئن شوید که می‌توانید درخواست‌های مجاز را با استفاده از راهنمای مجوز ما ارسال کنید.
سیاست های پشتیبانی شده
| نام خط مشی | شرح سیاست | نوع خط مشی API Enum Value |
|---|---|---|
| محتوای خطرناک | محتوایی که دسترسی به کالاها، خدمات و فعالیت‌های مضر را تسهیل، ترویج یا امکان‌پذیر می‌کند. | DANGEROUS_CONTENT |
| درخواست و تلاوت PII | محتوایی که اطلاعات یا داده های شخصی حساس یک فرد را درخواست یا فاش می کند. | PII_SOLICITING_RECITING |
| آزار و اذیت | محتوایی که مخرب، ارعاب‌کننده، قلدری یا توهین‌آمیز نسبت به افراد دیگر است. | HARASSMENT |
| صریح جنسی | محتوایی که ماهیت صریح جنسی دارد. | SEXUALLY_EXPLICIT |
| سخنان نفرت | محتوایی که عموماً به عنوان سخنان مشوق عداوت و تنفر پذیرفته شده است. | HATE_SPEECH |
| اطلاعات پزشکی | محتوایی که دسترسی به توصیه‌ها یا راهنمایی‌های پزشکی مضر را تسهیل، ترویج یا امکان‌پذیر می‌کند، ممنوع است. | MEDICAL_INFO |
| خشونت و گور | محتوایی که شامل توصیفات بیهوده خشونت و/یا غم واقع گرایانه است. | VIOLENCE_AND_GORE |
| فحاشی و فحاشی | محتوای حاوی الفاظ مبتذل، توهین آمیز یا توهین آمیز ممنوع است. | OBSCENITY_AND_PROFANITY |
قطعه کد
پایتون
با اجرای 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'],
)
برو
Checks API Go Client را با اجرای go get google.golang.org/api/checks/v1alpha نصب کنید.
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)
}
}
استراحت
توجه: این مثال از ابزار oauth2l CLI استفاده می کند.
شناسه پروژه Google Cloud خود را جایگزین YOUR_GCP_PROJECT_ID کنید که به 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 شما ادغام کرد، بسته به نیازهای خاص و تحمل ریسک شما. در اینجا چند نمونه از موارد استفاده رایج آورده شده است:
بدون مداخله گاردریل - ورود به سیستم
در این سناریو، Guardrails API بدون هیچ تغییری در رفتار برنامه استفاده می‌شود. با این حال، تخلفات احتمالی خط مشی برای اهداف نظارت و حسابرسی ثبت می شود. این اطلاعات بیشتر می تواند برای شناسایی خطرات بالقوه ایمنی LLM استفاده شود.
پایتون
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)
برو
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 ورودی های ناامن کاربر و پاسخ های مدل را مسدود می کند. هر دو را در برابر سیاست های ایمنی از پیش تعریف شده (مانند سخنان مشوق نفرت، محتوای خطرناک) بررسی می کند. این امر از ایجاد خروجی های بالقوه مضر توسط هوش مصنوعی جلوگیری می کند و از کاربران در برابر مواجهه با محتوای نامناسب محافظت می کند.
پایتون
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)
برو
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 زمینه کافی برای Guardrails داشته باشد تا قبل از فراخوانی API ارزیابی دقیقی انجام دهد.
تماس های محافظ سنکرون
پایتون
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)
برو
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
}
}
}
}
تماس های گاردیل ناهمزمان
پایتون
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())
برو
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 را توضیح دهید.
- مقدار سهمیه مورد نظر: مشخص کنید که چه مقدار سهمیه اضافی نیاز دارید.