שיטה: models.generateContent
יוצרת תשובה מהמודל בהינתן קלט GenerateContentRequest
.
יכולות הקלט משתנות בין המודלים, כולל מודלים מכווננים. פרטים נוספים זמינים במדריך המודלים ובמדריך הכוונון.
נקודת קצה
לשלוח
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:generateContent
פרמטרים של נתיב
model
string
חובה. השם של Model
שישמש ליצירת ההשלמה.
פורמט: name=models/{model}
הוא מופיע בפורמט models/{model}
.
גוף הבקשה
גוף הבקשה מכיל נתונים במבנה הבא:
contents[]
object (Content
)
חובה. תוכן השיחה הנוכחית עם המודל.
בשאילתות עם סיבוב אחד, מדובר באירוע יחיד. בשאילתות עם מספר פניות, זהו שדה חוזר שמכיל את היסטוריית השיחות + הבקשה האחרונה.
tools[]
object (Tool
)
זה שינוי אופציונלי. רשימה של Tools
שהמודל יכול להשתמש בהם כדי ליצור את התשובה הבאה.
Tool
הוא קטע קוד שמאפשר למערכת לקיים אינטראקציה עם מערכות חיצוניות כדי לבצע פעולה או קבוצת פעולות, מחוץ לידע ולהיקף של המודל. הכלי היחיד שנתמך כרגע הוא Function
.
toolConfig
object (ToolConfig
)
זה שינוי אופציונלי. הגדרת הכלי לכל Tool
שצוין בבקשה.
safetySettings[]
object (SafetySetting
)
זה שינוי אופציונלי. רשימה של מופעים ייחודיים של SafetySetting
לחסימת תוכן לא בטוח.
המדיניות הזו תיאכף בGenerateContentRequest.contents
ובGenerateContentResponse.candidates
. לכל סוג של SafetyCategory
יכולה להיות הגדרה אחת לכל היותר. ה-API יחסום תוכן ותשובות שלא יעמדו בערכי הסף שהוגדרו על ידי ההגדרות האלה. הרשימה הזו מבטלת את הגדרות ברירת המחדל לכל SafetyCategory
שצוינו בהגדרות הבטיחות. אם לא צוין SafetySetting
עבור SafetyCategory
מסוים ברשימה, ה-API ישתמש בהגדרת ברירת המחדל של בטיחות לקטגוריה הזו. קיימת תמיכה בקטגוריות פגיעה HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT ו-HARM_CATEGORY_HARASSMENT.
systemInstruction
object (Content
)
זה שינוי אופציונלי. הוראה למערכת למפתחים. כרגע אפשר להשתמש רק בטקסט.
generationConfig
object (GenerationConfig
)
זה שינוי אופציונלי. אפשרויות תצורה ליצירת מודל ולפלט שלו.
cachedContent
string
זה שינוי אופציונלי. שם התוכן שנשמר במטמון שמשמש כהקשר להצגת החיזוי. הערה: משמשת רק בשמירה מפורשת במטמון, שבה המשתמשים יכולים לשלוט בשמירה במטמון (למשל איזה תוכן לשמור במטמון) וליהנות מחיסכון מובטח בעלויות. פורמט: cachedContents/{cachedContent}
דוגמה לבקשה
טקסט
Python
Node.js
Kotlin
Swift
Dart
Java
תמונה
Python
Node.js
Kotlin
Swift
Dart
Java
אודיו
Python
Node.js
וידאו
Python
Node.js
צ'אט
Python
Node.js
קונכייה
Kotlin
Swift
Dart
Java
מטמון
Python
Node.js
מודל מכוונן
Python
מצב JSON
Python
Node.js
Kotlin
Swift
Dart
Java
ביצוע קוד
Python
Kotlin
Java
שליחת פונקציות
Python
Node.js
Kotlin
Swift
Dart
Java
הגדרת היצירה
Python
Node.js
קונכייה
Kotlin
Swift
Dart
Java
הגדרות בטיחות
Python
Node.js
קונכייה
Kotlin
Swift
Dart
Java
הוראה למערכת
Python
Node.js
Kotlin
Swift
Dart
Java
גוף התשובה
אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכלול מופע של GenerateContentResponse
.
השיטה: models.streamGenerateContent
יוצרת תשובה בסטרימינג מהמודל בהינתן קלט GenerateContentRequest
.
נקודת קצה
לשלוח
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:streamGenerateContent
פרמטרים של נתיב
model
string
חובה. השם של Model
שישמש ליצירת ההשלמה.
פורמט: name=models/{model}
הוא מופיע בפורמט models/{model}
.
גוף הבקשה
גוף הבקשה מכיל נתונים במבנה הבא:
contents[]
object (Content
)
חובה. תוכן השיחה הנוכחית עם המודל.
בשאילתות עם סיבוב אחד, מדובר באירוע יחיד. בשאילתות עם מספר פניות, זהו שדה חוזר שמכיל את היסטוריית השיחות + הבקשה האחרונה.
tools[]
object (Tool
)
זה שינוי אופציונלי. רשימה של Tools
שהמודל יכול להשתמש בהם כדי ליצור את התשובה הבאה.
Tool
הוא קטע קוד שמאפשר למערכת לקיים אינטראקציה עם מערכות חיצוניות כדי לבצע פעולה או קבוצת פעולות, מחוץ לידע ולהיקף של המודל. הכלי היחיד שנתמך כרגע הוא Function
.
toolConfig
object (ToolConfig
)
זה שינוי אופציונלי. הגדרת הכלי לכל Tool
שצוין בבקשה.
safetySettings[]
object (SafetySetting
)
זה שינוי אופציונלי. רשימה של מופעים ייחודיים של SafetySetting
לחסימת תוכן לא בטוח.
המדיניות הזו תיאכף בGenerateContentRequest.contents
ובGenerateContentResponse.candidates
. לכל סוג של SafetyCategory
יכולה להיות הגדרה אחת לכל היותר. ה-API יחסום תוכן ותשובות שלא יעמדו בערכי הסף שהוגדרו על ידי ההגדרות האלה. הרשימה הזו מבטלת את הגדרות ברירת המחדל לכל SafetyCategory
שצוינו בהגדרות הבטיחות. אם לא צוין SafetySetting
עבור SafetyCategory
מסוים ברשימה, ה-API ישתמש בהגדרת ברירת המחדל של בטיחות לקטגוריה הזו. קיימת תמיכה בקטגוריות פגיעה HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT ו-HARM_CATEGORY_HARASSMENT.
systemInstruction
object (Content
)
זה שינוי אופציונלי. הוראה למערכת למפתחים. כרגע אפשר להשתמש רק בטקסט.
generationConfig
object (GenerationConfig
)
זה שינוי אופציונלי. אפשרויות תצורה ליצירת מודל ולפלט שלו.
cachedContent
string
זה שינוי אופציונלי. שם התוכן שנשמר במטמון שמשמש כהקשר להצגת החיזוי. הערה: משמשת רק בשמירה מפורשת במטמון, שבה המשתמשים יכולים לשלוט בשמירה במטמון (למשל איזה תוכן לשמור במטמון) וליהנות מחיסכון מובטח בעלויות. פורמט: cachedContents/{cachedContent}
דוגמה לבקשה
טקסט
Python
Node.js
Kotlin
Swift
Dart
Java
תמונה
Python
Node.js
Kotlin
Swift
Dart
Java
וידאו
Python
Node.js
Kotlin
Java
צ'אט
Python
Node.js
קונכייה
Kotlin
Swift
Dart
Java
גוף התשובה
אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכלול זרם של GenerateContentResponse
מופעים.
GenerateContentResponse
התשובה מהמודל שתומכת במועמדים מרובים.
הערה לגבי סיווגי בטיחות וסינון תוכן. הם מדווחים גם להנחיות בGenerateContentResponse.prompt_feedback
וגם לכל מועמד בfinishReason
ובsafetyRatings
. חוזה ה-API הוא: - או שכל המועמדים המבוקשים מוחזרים או שלא מוחזרים אף מועמדים - לא מוחזרים מועמדים רק אם משהו השתבש בהנחיה (ראו promptFeedback
) - משוב על כל מועמד מדווח ב-finishReason
וב-safetyRatings
.
ייצוג JSON |
---|
{ "candidates": [ { object ( |
candidates[]
object (Candidate
)
התשובות של המועמדים מהמודל.
promptFeedback
object (PromptFeedback
)
מחזירה את המשוב של ההנחיה שקשורה למסנני התוכן.
usageMetadata
object (UsageMetadata
)
פלט בלבד. מטא-נתונים של בקשות הגנרציה שימוש באסימון.
PromptFeedback
קבוצת מטא-נתונים של המשוב שההנחיה שצוינה ב-GenerateContentRequest.content
.
ייצוג JSON |
---|
{ "blockReason": enum ( |
blockReason
enum (BlockReason
)
זה שינוי אופציונלי. אם היא מוגדרת, ההנחיה נחסמה ולא מוחזרים מועמדים. נסחו מחדש את ההנחיה.
safetyRatings[]
object (SafetyRating
)
דירוגים של בטיחות ההצעה. לכל קטגוריה יש דירוג אחד לכל היותר.
BlockReason
מציינת מה הייתה הסיבה לחסימת ההנחיה.
טיפוסים בני מנייה (enum) | |
---|---|
BLOCK_REASON_UNSPECIFIED |
ערך ברירת המחדל. הערך הזה לא בשימוש. |
SAFETY |
ההנחיה נחסמה מטעמי בטיחות. אפשר לבדוק את safetyRatings כדי להבין איזו קטגוריית בטיחות חסמה אותה. |
OTHER |
ההנחיה נחסמה בגלל סיבות לא ידועות. |
UsageMetadata
מטא-נתונים לגבי השימוש באסימון של בקשת הגנרציה.
ייצוג JSON |
---|
{ "promptTokenCount": integer, "cachedContentTokenCount": integer, "candidatesTokenCount": integer, "totalTokenCount": integer } |
promptTokenCount
integer
מספר האסימונים בהודעה. כשמוגדר תוכן שנשמר במטמון, זה עדיין הגודל הכולל של ההנחיות האפקטיביות. כלומר, זה כולל את מספר האסימונים בתוכן שנשמר במטמון.
cachedContentTokenCount
integer
מספר האסימונים בחלק שנשמר במטמון של ההנחיה, כלומר בתוכן ששמור במטמון.
candidatesTokenCount
integer
המספר הכולל של האסימונים האפשריים בכל המועמדים שנוצרו.
totalTokenCount
integer
מספר האסימונים הכולל לבקשת היצירה (הנחיה + מועמדים).
מועמד
- ייצוג JSON
- FinishReason
- GroundingAttribution
- AttributionSourceId
- GroundingPassageId
- SemanticRetrieverChunk
המודל הרצוי לתשובות נוצר מהמודל.
ייצוג JSON |
---|
{ "content": { object ( |
content
object (Content
)
פלט בלבד. תוכן שנוצר שהוחזר מהמודל.
finishReason
enum (FinishReason
)
זה שינוי אופציונלי. פלט בלבד. הסיבה לכך שהמודל הפסיק ליצור אסימונים.
אם הם ריקים, המודל לא הפסיק ליצור את האסימונים.
safetyRatings[]
object (SafetyRating
)
רשימת דירוגים לשמירה על הבטיחות של המועמדים לתשובות.
לכל קטגוריה יש דירוג אחד לכל היותר.
citationMetadata
object (CitationMetadata
)
פלט בלבד. ציטוטים ביבליוגרפיים של המועמדים שנוצרו על ידי המודל.
אפשר לאכלס את השדה הזה בפרטי הקראה עבור כל טקסט שנכלל ב-content
. אלה פסקאות ש"מצוטטות" מחומרים שמוגנים בזכויות יוצרים בנתוני האימון הבסיסיים של ה-LLM.
tokenCount
integer
פלט בלבד. מספר האסימונים למועמד הזה.
groundingAttributions[]
object (GroundingAttribution
)
פלט בלבד. פרטי שיוך (Attribution) למקורות שתרמו לתשובה מבוססת.
השדה הזה מאוכלס ב-GenerateAnswer
שיחות.
index
integer
פלט בלבד. אינדקס המועמד ברשימת המועמדים.
FinishReason
מגדיר את הסיבה לכך שהמודל הפסיק ליצור אסימונים.
טיפוסים בני מנייה (enum) | |
---|---|
FINISH_REASON_UNSPECIFIED |
ערך ברירת המחדל. הערך הזה לא בשימוש. |
STOP |
נקודת העצירה הטבעית של המודל או רצף העצירה שצוין. |
MAX_TOKENS |
הגעת למספר האסימונים המקסימלי שצוין בבקשה. |
SAFETY |
התוכן של המועמד סומן מטעמי בטיחות. |
RECITATION |
התוכן של המועמד סומן מסיבות של הקראה. |
LANGUAGE |
התוכן של המועמד סומן כי הוא מכיל שפה שאינה נתמכת. |
OTHER |
סיבה לא ידועה. |
GroundingAttribution
שיוך למקור שתרם לתשובה.
ייצוג JSON |
---|
{ "sourceId": { object ( |
sourceId
object (AttributionSourceId
)
פלט בלבד. המזהה של המקור שתורם לשיוך הזה.
content
object (Content
)
תוכן המקור שממנו מורכב השיוך הזה.
AttributionSourceId
המזהה של המקור שתורם לשיוך הזה.
ייצוג JSON |
---|
{ // Union field |
שדה איחוד source
.
source
יכול להיות רק אחת מהאפשרויות הבאות:
groundingPassage
object (GroundingPassageId
)
מזהה של פסקה בתוך השורה.
semanticRetrieverChunk
object (SemanticRetrieverChunk
)
מזהה של Chunk
שאוחזר באמצעות שליפה סמנטית.
GroundingPassageId
מזהה של חלק בתוך GroundingPassage
.
ייצוג JSON |
---|
{ "passageId": string, "partIndex": integer } |
passageId
string
פלט בלבד. מזהה של הקטע שתואם לערך GroundingPassage.id
של GenerateAnswerRequest
.
partIndex
integer
פלט בלבד. אינדקס החלק בתוך GroundingPassage.content
של GenerateAnswerRequest
.
SemanticRetrieverChunk
מזהה של Chunk
שאוחזר באמצעות הכלי האחזור הסמנטי שצוין ב-GenerateAnswerRequest
באמצעות SemanticRetrieverConfig
.
ייצוג JSON |
---|
{ "source": string, "chunk": string } |
source
string
פלט בלבד. שם המקור שתואם ל-SemanticRetrieverConfig.source
של הבקשה. לדוגמה: corpora/123
או corpora/123/documents/abc
chunk
string
פלט בלבד. השם של Chunk
שמכיל את הטקסט המשויך. לדוגמה: corpora/123/documents/abc/chunks/xyz
CitationMetadata
אוסף של פרטי ייחוס של מקורות לחלק מהתוכן.
ייצוג JSON |
---|
{
"citationSources": [
{
object ( |
citationSources[]
object (CitationSource
)
ציטוטים למקורות עם תשובה ספציפית.
CitationSource
ציטוט אל מקור עבור חלק מתשובה ספציפית.
ייצוג JSON |
---|
{ "startIndex": integer, "endIndex": integer, "uri": string, "license": string } |
startIndex
integer
זה שינוי אופציונלי. תחילת המקטע של התגובה שמשויכת למקור הזה.
האינדקס מציין את תחילת הקטע, הנמדד בבייטים.
endIndex
integer
זה שינוי אופציונלי. סוף הפלח המשויך, לא כולל.
uri
string
זה שינוי אופציונלי. URI שמשויך כמקור של חלק מהטקסט.
license
string
זה שינוי אופציונלי. רישיון לפרויקט ב-GitHub שמשויך כמקור לפילוח.
כדי לקבל ציטוטים ביבליוגרפיים נדרשים פרטי רישיון.
GenerationConfig
אפשרויות תצורה ליצירת מודל ולפלט שלו. יכול להיות שחלק מהפרמטרים לא ניתנים להגדרה בכל מודל.
ייצוג JSON |
---|
{
"stopSequences": [
string
],
"responseMimeType": string,
"responseSchema": {
object ( |
stopSequences[]
string
זה שינוי אופציונלי. הקבוצה של רצפי תווים (עד 5) שיפסיקו ליצור פלט. אם צוין, ה-API יפסיק להופיע בפעם הראשונה של רצף עצירה. רצף העצירה לא ייכלל כחלק מהתשובה.
responseMimeType
string
זה שינוי אופציונלי. mimetype של תגובת הפלט של הטקסט המועמד שנוצר. mimetype נתמך: text/plain
: (ברירת מחדל) פלט טקסט. application/json
: תגובת JSON במועמדים.
responseSchema
object (Schema
)
זה שינוי אופציונלי. סכימת תגובת פלט של טקסט המועמד שנוצר כאשר סוג MIME של התשובה יכול לכלול סכימה. הסכימה יכולה להיות אובייקטים, פרימיטיביים או מערכים, והיא קבוצת משנה של סכימת OpenAPI.
אם המדיניות מוגדרת, יש להגדיר גם תגובה תואמתMimeType. mimetypes תואמים: application/json
: סכימה לתגובת JSON.
candidateCount
integer
זה שינוי אופציונלי. מספר התגובות שנוצרו להחזרה.
נכון לעכשיו, אפשר להגדיר את הערך הזה רק כ-1. אם המדיניות לא מוגדרת, ברירת המחדל תהיה 1.
maxOutputTokens
integer
זה שינוי אופציונלי. המספר המקסימלי של אסימונים שאפשר לכלול במועמד.
הערה: ערך ברירת המחדל משתנה בהתאם למודל. כדאי לעיין במאפיין Model.output_token_limit
של Model
שמוחזר מהפונקציה getModel
.
temperature
number
זה שינוי אופציונלי. המדיניות קובעת את רמת הרנדומיזציה של הפלט.
הערה: ערך ברירת המחדל משתנה בהתאם למודל. כדאי לעיין במאפיין Model.temperature
של Model
שמוחזר מהפונקציה getModel
.
הערכים יכולים לנוע בין [0.0, 2.0].
topP
number
זה שינוי אופציונלי. ההסתברות המצטברת המקסימלית של אסימונים שיש להביא בחשבון במהלך הדגימה.
המודל משתמש בדגימת גרעין, לפי חלוקה בקנטקי ולהפך.
האסימונים ממוינים לפי ההסתברויות שהוקצו להם, כך שהמערכת תתייחס רק לאסימונים עם הסיכוי הכי גבוה. דגימה מסוג 'אליפות גבוהה' מגבילה באופן ישיר את המספר המקסימלי של אסימונים שצריך להשתמש בהם, ואילו דגימת ה-Nucleus מגבילה את מספר האסימונים על סמך ההסתברות המצטברת.
הערה: ערך ברירת המחדל משתנה בהתאם למודל. כדאי לעיין במאפיין Model.top_p
של Model
שמוחזר מהפונקציה getModel
.
topK
integer
זה שינוי אופציונלי. המספר המקסימלי של אסימונים שצריך לקחת בחשבון במהלך הדגימה.
מודלים משתמשים בדגימת גרעין או בדגימה משולבת של גרעין תלישה וגרעיניות. דגימת הדגלים מבוססת על סט של topK
האסימונים בעלי הסבירות הגבוהה ביותר. מודלים שפועלים עם דגימת גרעין לא מאפשרים הגדרה של topK.
הערה: ערך ברירת המחדל משתנה בהתאם למודל. כדאי לעיין במאפיין Model.top_k
של Model
שמוחזר מהפונקציה getModel
. שדה topK
ריק ב-Model
מציין שהמודל לא מחיל דגימת Ktop ולא מאפשר להגדיר topK
בבקשות.
HarmCategory
הקטגוריה של הדירוג.
הקטגוריות האלה כוללות סוגים שונים של נזקים שייתכן שמפתחים ירצו להתאים.
טיפוסים בני מנייה (enum) | |
---|---|
HARM_CATEGORY_UNSPECIFIED |
לא צוינה קטגוריה. |
HARM_CATEGORY_DEROGATORY |
תגובות שליליות או מזיקות שמטרגטות את הזהות או את המאפיין המוגן. |
HARM_CATEGORY_TOXICITY |
תוכן בוטה, לא מכבד או גס. |
HARM_CATEGORY_VIOLENCE |
תיאורים של תרחישים שבהם מוצגת אלימות כלפי אדם או קבוצה, או תיאורים כלליים של שפיכות דמים. |
HARM_CATEGORY_SEXUAL |
כולל התייחסות למעשים מיניים או לתוכן גס אחר. |
HARM_CATEGORY_MEDICAL |
עידוד של ייעוץ רפואי לא מאומת. |
HARM_CATEGORY_DANGEROUS |
תוכן מסוכן שמקדם גרימת נזק, מעודד גרימת נזק או עוזר לבצע פעולות מזיקות. |
HARM_CATEGORY_HARASSMENT |
תוכן שמטרתו הטרדה. |
HARM_CATEGORY_HATE_SPEECH |
דברי שטנה ותוכן. |
HARM_CATEGORY_SEXUALLY_EXPLICIT |
תוכן מיני בוטה. |
HARM_CATEGORY_DANGEROUS_CONTENT |
תוכן מסוכן. |
SafetyRating
דירוג הבטיחות של קטע התוכן.
דירוג הבטיחות כולל את הקטגוריה של הפגיעה ואת רמת ההסתברות לפגיעה בקטגוריה הזו עבור קטע תוכן. התוכן מסווג בתור בטיחות בכמה קטגוריות של פגיעה, וההסתברות לסיווג הנזק כוללת כאן.
ייצוג JSON |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
חובה. הקטגוריה של הדירוג הזה.
probability
enum (HarmProbability
)
חובה. הסבירות לפגיעה בתוכן הזה.
blocked
boolean
האם התוכן הזה נחסם בגלל הסיווג הזה?
HarmProbability
הסבירות שקטע תוכן מסוים מזיק.
מערכת הסיווג מספקת את הסבירות שהתוכן לא בטוח. העובדה הזו לא מצביעה על חומרת הפגיעה בקטע תוכן.
טיפוסים בני מנייה (enum) | |
---|---|
HARM_PROBABILITY_UNSPECIFIED |
לא צוינה הסתברות. |
NEGLIGIBLE |
יש סיכוי זניח שהתוכן יהיה לא בטוח. |
LOW |
יש סיכוי נמוך שהתוכן יהיה לא בטוח. |
MEDIUM |
יש סיכוי בינוני שהתוכן יהיה לא בטוח. |
HIGH |
יש סיכוי גבוה שהתוכן יהיה לא בטוח. |
SafetySetting
הגדרת הבטיחות, שמשפיעה על ההתנהגות של חסימת הבטיחות.
העברה של הגדרת בטיחות לקטגוריה משנה את הסבירות שהתוכן ייחסם.
ייצוג JSON |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
חובה. הקטגוריה של ההגדרה הזו.
threshold
enum (HarmBlockThreshold
)
חובה. קובעת את סף ההסתברות שבו הנזק נחסם.
HarmBlockThreshold
חסימה לפי הסבירות לפגיעה מסוימת, ומעבר לה.
טיפוסים בני מנייה (enum) | |
---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED |
לא צוין סף. |
BLOCK_LOW_AND_ABOVE |
נאפשר הצגת תוכן בסטטוס 'שלילי'. |
BLOCK_MEDIUM_AND_ABOVE |
נאפשר הצגת תוכן עם הערכים NEGLIGIBLE ו-LOW. |
BLOCK_ONLY_HIGH |
מותר להציג תוכן עם הערכים NEGLIGIBLE, LOW, ו-MEDIUM. |
BLOCK_NONE |
יאושר כל התוכן. |