روش: models.generateContent
پاسخی را از مدل با یک ورودی GenerateContentRequest
ایجاد می کند.
قابلیت های ورودی بین مدل ها از جمله مدل های تنظیم شده متفاوت است. برای جزئیات به راهنمای مدل و راهنمای تنظیم مراجعه کنید.
نقطه پایانی
پستhttps://generativelanguage.googleapis.com/v1beta/{model=models/*}:generateContent
پارامترهای مسیر
string
model
ضروری. نام 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}
درخواست نمونه
متن
پایتون
Node.js
کاتلین
سریع
دارت
جاوا
تصویر
پایتون
Node.js
کاتلین
سریع
دارت
جاوا
سمعی
پایتون
Node.js
ویدیو
پایتون
Node.js
چت کنید
پایتون
Node.js
پوسته
کاتلین
سریع
دارت
جاوا
حافظه پنهان
پایتون
Node.js
مدل کوک شده
پایتون
حالت JSON
پایتون
Node.js
کاتلین
سریع
دارت
جاوا
اجرای کد
پایتون
کاتلین
جاوا
فراخوانی تابع
پایتون
Node.js
کاتلین
سریع
دارت
جاوا
پیکربندی نسل
پایتون
Node.js
پوسته
کاتلین
سریع
دارت
جاوا
تنظیمات ایمنی
پایتون
Node.js
پوسته
کاتلین
سریع
دارت
جاوا
دستورالعمل سیستم
پایتون
Node.js
کاتلین
سریع
دارت
جاوا
بدن پاسخگو
در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی نمونه ای از GenerateContentResponse
است.
روش: models.streamGenerateContent
یک پاسخ جریانی از مدل با یک ورودی GenerateContentRequest
ایجاد می کند.
نقطه پایانی
پستhttps://generativelanguage.googleapis.com/v1beta/{model=models/*}:streamGenerateContent
پارامترهای مسیر
string
model
ضروری. نام 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}
درخواست نمونه
متن
پایتون
Node.js
کاتلین
سریع
دارت
جاوا
تصویر
پایتون
Node.js
کاتلین
سریع
دارت
جاوا
ویدیو
پایتون
Node.js
کاتلین
جاوا
چت کنید
پایتون
Node.js
پوسته
کاتلین
سریع
دارت
جاوا
بدن پاسخگو
در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی جریانی از نمونه های GenerateContentResponse
است.
Generate ContentResponse
پاسخ از مدلی که از چندین نامزد پشتیبانی می کند.
توجه به رتبه بندی ایمنی و فیلتر محتوا. آنها هم برای prompt در 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
مشخص می کند که دلیل مسدود شدن درخواست چه بوده است.
Enums | |
---|---|
BLOCK_REASON_UNSPECIFIED | مقدار پیش فرض. این مقدار استفاده نشده است. |
SAFETY | درخواست به دلایل ایمنی مسدود شد. میتوانید safetyRatings بررسی کنید تا متوجه شوید کدام دسته ایمنی آن را مسدود کرده است. |
OTHER | درخواست به دلایل نامعلوم مسدود شد. |
UsageMetadata
فراداده در مورد استفاده از رمز درخواست تولید.
نمایندگی JSON |
---|
{ "promptTokenCount": integer, "cachedContentTokenCount": integer, "candidatesTokenCount": integer, "totalTokenCount": integer } |
promptTokenCount
integer
تعداد توکن ها در اعلان. وقتی cachedContent تنظیم میشود، این اندازه هنوز کل اندازه مؤثر است. یعنی این شامل تعداد نشانه های موجود در محتوای کش می شود.
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
)
فقط خروجی اطلاعات انتساب برای منابعی که به یک پاسخ پایه کمک کرده اند.
این فیلد برای تماسهای GenerateAnswer
پر شده است.
integer
index
فقط خروجی فهرست نامزد در فهرست نامزدها.
FinishReason
دلیل توقف تولید توکن ها توسط مدل را مشخص می کند.
Enums | |
---|---|
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
که از طریق Semantic Retriever واکشی شده است.
GroundingPassageId
شناسه بخشی در GroundingPassage
.
نمایندگی JSON |
---|
{ "passageId": string, "partIndex": integer } |
string
passageId
فقط خروجی شناسه متن مطابق با GenerateAnswerRequest
's GroundingPassage.id
.
partIndex
integer
فقط خروجی فهرست بخش در GroundingPassage.content
GenerateAnswerRequest
.
SemanticRetrieverChunk
شناسه یک Chunk
بازیابی شده از طریق Semantic Retriever مشخص شده در GenerateAnswerRequest
با استفاده از SemanticRetrieverConfig
.
نمایندگی JSON |
---|
{ "source": string, "chunk": string } |
string
source
فقط خروجی نام منبعی که با SemanticRetrieverConfig.source
درخواست مطابقت دارد. مثال: corpora/123
یا corpora/123/documents/abc
string
chunk
فقط خروجی نام Chunk
حاوی متن نسبت داده شده. مثال: corpora/123/documents/abc/chunks/xyz
CitationMetadata
مجموعه ای از منابع منبع برای یک قطعه محتوا.
نمایندگی JSON |
---|
{
"citationSources": [
{
object ( |
citationSources[]
object ( CitationSource
)
استناد به منابع برای پاسخ خاص.
منبع استناد
استناد به یک منبع برای بخشی از یک پاسخ خاص.
نمایندگی JSON |
---|
{ "startIndex": integer, "endIndex": integer, "uri": string, "license": string } |
startIndex
integer
اختیاری. شروع بخش پاسخی که به این منبع نسبت داده می شود.
شاخص شروع بخش را نشان می دهد که در بایت اندازه گیری می شود.
endIndex
integer
اختیاری. انتهای بخش منتسب، انحصاری.
string
uri
اختیاری. URI که به عنوان منبع بخشی از متن نسبت داده می شود.
string
license
اختیاری. مجوز برای پروژه GitHub که به عنوان منبعی برای بخش نسبت داده می شود.
اطلاعات مجوز برای استناد کد مورد نیاز است.
GenerationConfig
گزینه های پیکربندی برای تولید مدل و خروجی ها. ممکن است همه پارامترها برای هر مدلی قابل تنظیم نباشند.
نمایندگی JSON |
---|
{
"stopSequences": [
string
],
"responseMimeType": string,
"responseSchema": {
object ( |
string
stopSequences[]
اختیاری. مجموعه ای از دنباله های کاراکتر (تا 5) که تولید خروجی را متوقف می کند. اگر مشخص شود، API در اولین ظاهر یک توالی توقف متوقف خواهد شد. توالی توقف به عنوان بخشی از پاسخ درج نخواهد شد.
string
responseMimeType
اختیاری. نوع پاسخ خروجی متن نامزد تولید شده. نوع mime پشتیبانی شده: text/plain
: (پیشفرض) خروجی متن. application/json
: پاسخ JSON در نامزدها.
responseSchema
object ( Schema
)
اختیاری. طرح پاسخ خروجی متن نامزد تولید شده زمانی که نوع میم پاسخ می تواند طرحواره داشته باشد. طرحواره می تواند اشیا، اولیه یا آرایه باشد و زیرمجموعه ای از طرحواره OpenAPI است.
در صورت تنظیم، یک answerMimeType سازگار نیز باید تنظیم شود. mimetypes سازگار: application/json
: Schema برای پاسخ JSON.
candidateCount
integer
اختیاری. تعداد پاسخ های تولید شده برای بازگشت.
در حال حاضر، این مقدار را فقط می توان روی 1 تنظیم کرد. اگر تنظیم نشود، به طور پیش فرض روی 1 خواهد بود.
maxOutputTokens
integer
اختیاری. حداکثر تعداد نشانه هایی که باید در یک نامزد گنجانده شود.
توجه: مقدار پیش فرض بسته به مدل متفاوت است، به ویژگی Model.output_token_limit
Model
بازگشتی از تابع getModel
مراجعه کنید.
number
temperature
اختیاری. تصادفی بودن خروجی را کنترل می کند.
توجه: مقدار پیش فرض بر اساس مدل متفاوت است، به ویژگی Model.temperature
Model
بازگشتی از تابع getModel
مراجعه کنید.
مقادیر می توانند از [0.0، 2.0] متغیر باشند.
number
topP
اختیاری. حداکثر احتمال تجمعی نشانه هایی که باید در هنگام نمونه گیری در نظر گرفته شوند.
این مدل از نمونه برداری ترکیبی Top-k و هسته استفاده می کند.
توکن ها بر اساس احتمالات اختصاص داده شده مرتب می شوند تا فقط محتمل ترین توکن ها در نظر گرفته شوند. نمونهبرداری Top-k مستقیماً حداکثر تعداد توکنهای مورد نظر را محدود میکند، در حالی که نمونهبرداری هستهای تعداد توکنها را بر اساس احتمال تجمعی محدود میکند.
توجه: مقدار پیش فرض بر اساس مدل متفاوت است، به ویژگی Model.top_p
Model
بازگشتی از تابع getModel
مراجعه کنید.
topK
integer
اختیاری. حداکثر تعداد نشانه هایی که باید در هنگام نمونه گیری در نظر گرفته شود.
مدل ها از نمونه برداری هسته یا نمونه برداری ترکیبی Top-k و هسته استفاده می کنند. نمونه گیری Top-k مجموعه ای از محتمل ترین توکن های topK
را در نظر می گیرد. مدلهایی که با نمونهبرداری هسته اجرا میشوند اجازه تنظیم topK را نمیدهند.
توجه: مقدار پیش فرض بر اساس مدل متفاوت است، به ویژگی Model.top_k
Model
بازگشتی از تابع getModel
مراجعه کنید. فیلد خالی topK
در Model
نشان میدهد که مدل نمونهگیری top-k را اعمال نمیکند و اجازه تنظیم topK
در درخواستها را نمیدهد.
Harm Category
دسته بندی یک رتبه.
این دسته ها انواع مختلفی از آسیب ها را پوشش می دهند که توسعه دهندگان ممکن است بخواهند آنها را تعدیل کنند.
Enums | |
---|---|
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 | محتوای خطرناک |
رتبه ایمنی
رتبه بندی ایمنی برای یک قطعه محتوا.
رتبه بندی ایمنی شامل دسته آسیب و سطح احتمال آسیب در آن دسته برای یک قطعه محتوا است. محتوا برای ایمنی در تعدادی از دستههای آسیب طبقهبندی شده است و احتمال طبقهبندی آسیب در اینجا گنجانده شده است.
نمایندگی JSON |
---|
{ "category": enum ( |
category
enum ( HarmCategory
)
ضروری. دسته بندی برای این رتبه بندی
probability
enum ( HarmProbability
)
ضروری. احتمال آسیب برای این محتوا.
boolean
blocked
آیا این محتوا به دلیل این رتبه بندی مسدود شده است؟
احتمال آسیب
احتمال مضر بودن یک قطعه محتوا.
سیستم طبقه بندی احتمال ناامن بودن محتوا را می دهد. این نشان دهنده شدت آسیب برای یک قطعه محتوا نیست.
Enums | |
---|---|
HARM_PROBABILITY_UNSPECIFIED | احتمال نامشخص است. |
NEGLIGIBLE | احتمال ناامن بودن محتوا ناچیز است. |
LOW | احتمال ناامن بودن محتوا کم است. |
MEDIUM | محتوا شانس متوسطی برای ناامن شدن دارد. |
HIGH | محتوا شانس بالایی برای ناامن بودن دارد. |
SafetySetting
تنظیم ایمنی، بر رفتار انسداد ایمنی تأثیر می گذارد.
تصویب یک تنظیم ایمنی برای یک دسته، احتمال مسدود شدن محتوا را تغییر می دهد.
نمایندگی JSON |
---|
{ "category": enum ( |
category
enum ( HarmCategory
)
ضروری. دسته برای این تنظیم.
threshold
enum ( HarmBlockThreshold
)
ضروری. آستانه احتمال مسدود شدن آسیب را کنترل می کند.
HarmBlockThreshold
مسدود کردن در و فراتر از یک احتمال آسیب مشخص.
Enums | |
---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | آستانه مشخص نیست. |
BLOCK_LOW_AND_ABOVE | محتوای با NEGLIGIBLE مجاز خواهد بود. |
BLOCK_MEDIUM_AND_ABOVE | محتوای با NEGLIGIBLE و LOW مجاز خواهد بود. |
BLOCK_ONLY_HIGH | محتوای با NEGLIGIBLE، LOW، و MEDIUM مجاز خواهد بود. |
BLOCK_NONE | تمامی مطالب مجاز خواهند بود. |