Metodo: model.generateContent
- Endpoint
- Parametri percorso
- Corpo della richiesta
- Corpo della risposta
- Ambiti di autorizzazione
- Richiesta di esempio
Genera una risposta dal modello dato un input GenerateContentRequest
.
Le capacità di input variano tra i modelli, inclusi i modelli ottimizzati. Per dettagli, consulta la guida ai modelli e la guida all'ottimizzazione.
Endpoint
pubblica
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:generateContent
Parametri del percorso
model
string
Obbligatorio. Il nome dell'evento Model
da utilizzare per generare il completamento.
Formato: name=models/{model}
. Il formato è models/{model}
.
Corpo della richiesta
Il corpo della richiesta contiene dati con la seguente struttura:
contents[]
object (Content
)
Obbligatorio. I contenuti della conversazione corrente con il modello.
Per le query a turno singolo, si tratta di una singola istanza. Per le query in più passaggi, si tratta di un campo ripetuto contenente la cronologia delle conversazioni e l'ultima richiesta.
tools[]
object (Tool
)
(Facoltativo) Un elenco di Tools
che il modello potrebbe utilizzare per generare la risposta successiva.
Un Tool
è una porzione di codice che consente al sistema di interagire con sistemi esterni per eseguire un'azione o un insieme di azioni al di fuori delle conoscenze e dell'ambito del modello. Al momento l'unico strumento supportato è Function
.
toolConfig
object (ToolConfig
)
(Facoltativo) Configurazione dello strumento per qualsiasi Tool
specificato nella richiesta.
safetySettings[]
object (SafetySetting
)
(Facoltativo) Un elenco di istanze SafetySetting
univoche per il blocco di contenuti non sicuri.
Questa norma verrà applicata in modo forzato a GenerateContentRequest.contents
e GenerateContentResponse.candidates
. Non dovrebbe essere presente più di un'impostazione per ogni tipo di SafetyCategory
. L'API bloccherà tutti i contenuti e le risposte che non rispetteranno le soglie impostate da queste impostazioni. Questo elenco sostituisce le impostazioni predefinite per ogni SafetyCategory
specificato in safetySettings. Se non è presente alcun valore SafetySetting
per un determinato SafetyCategory
nell'elenco, l'API utilizzerà l'impostazione di sicurezza predefinita per la categoria in questione. Sono supportate le categorie di danni HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT e HARM_CATEGORY_HARASSMENT.
systemInstruction
object (Content
)
(Facoltativo) Istruzione di sistema impostata dallo sviluppatore. Al momento, solo testo.
generationConfig
object (GenerationConfig
)
(Facoltativo) Opzioni di configurazione per la generazione e gli output del modello.
cachedContent
string
(Facoltativo) Il nome dei contenuti memorizzati nella cache utilizzati come contesto per fornire la previsione. Nota: utilizzato solo nella memorizzazione nella cache esplicita, dove gli utenti possono controllare la memorizzazione nella cache (ad es. quali contenuti memorizzare nella cache) e usufruire di risparmi sui costi garantiti. Formato: cachedContents/{cachedContent}
Esempio di richiesta
Testo
Python
Node.js
Kotlin
Swift
Dart
Java
Immagine
Python
Node.js
Kotlin
Swift
Dart
Java
Audio
Python
Node.js
Video
Python
Node.js
Chat
Python
Node.js
Conchiglia
Kotlin
Swift
Dart
Java
Cache
Python
Node.js
Modello ottimizzato
Python
Modalità JSON
Python
Node.js
Kotlin
Swift
Dart
Java
Esecuzione del codice
Python
Kotlin
Java
Chiamata di funzione
Python
Node.js
Kotlin
Swift
Dart
Java
Configurazione di generazione
Python
Node.js
Conchiglia
Kotlin
Swift
Dart
Java
Impostazioni di sicurezza
Python
Node.js
Conchiglia
Kotlin
Swift
Dart
Java
Istruzione di sistema
Python
Node.js
Kotlin
Swift
Dart
Java
Corpo della risposta
In caso di esito positivo, il corpo della risposta contiene un'istanza di GenerateContentResponse
.
Metodo: models.streamGenerateContent
- Endpoint
- Parametri percorso
- Corpo della richiesta
- Corpo della risposta
- Ambiti di autorizzazione
- Richiesta di esempio
Genera una risposta in modalità flusso dal modello dato un input GenerateContentRequest
.
Endpoint
pubblica
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:streamGenerateContent
Parametri del percorso
model
string
Obbligatorio. Il nome dell'evento Model
da utilizzare per generare il completamento.
Formato: name=models/{model}
. Il formato è models/{model}
.
Corpo della richiesta
Il corpo della richiesta contiene dati con la seguente struttura:
contents[]
object (Content
)
Obbligatorio. I contenuti della conversazione corrente con il modello.
Per le query a turno singolo, si tratta di una singola istanza. Per le query in più passaggi, si tratta di un campo ripetuto contenente la cronologia delle conversazioni e l'ultima richiesta.
tools[]
object (Tool
)
(Facoltativo) Un elenco di Tools
che il modello potrebbe utilizzare per generare la risposta successiva.
Un Tool
è una porzione di codice che consente al sistema di interagire con sistemi esterni per eseguire un'azione o un insieme di azioni al di fuori delle conoscenze e dell'ambito del modello. Al momento l'unico strumento supportato è Function
.
toolConfig
object (ToolConfig
)
(Facoltativo) Configurazione dello strumento per qualsiasi Tool
specificato nella richiesta.
safetySettings[]
object (SafetySetting
)
(Facoltativo) Un elenco di istanze SafetySetting
univoche per il blocco di contenuti non sicuri.
Questa norma verrà applicata in modo forzato a GenerateContentRequest.contents
e GenerateContentResponse.candidates
. Non dovrebbe essere presente più di un'impostazione per ogni tipo di SafetyCategory
. L'API bloccherà tutti i contenuti e le risposte che non rispetteranno le soglie impostate da queste impostazioni. Questo elenco sostituisce le impostazioni predefinite per ogni SafetyCategory
specificato in safetySettings. Se non è presente alcun valore SafetySetting
per un determinato SafetyCategory
nell'elenco, l'API utilizzerà l'impostazione di sicurezza predefinita per la categoria in questione. Sono supportate le categorie di danni HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT e HARM_CATEGORY_HARASSMENT.
systemInstruction
object (Content
)
(Facoltativo) Istruzione di sistema impostata dallo sviluppatore. Al momento, solo testo.
generationConfig
object (GenerationConfig
)
(Facoltativo) Opzioni di configurazione per la generazione e gli output del modello.
cachedContent
string
(Facoltativo) Il nome dei contenuti memorizzati nella cache utilizzati come contesto per fornire la previsione. Nota: utilizzato solo nella memorizzazione nella cache esplicita, dove gli utenti possono controllare la memorizzazione nella cache (ad es. quali contenuti memorizzare nella cache) e usufruire di risparmi sui costi garantiti. Formato: cachedContents/{cachedContent}
Esempio di richiesta
Testo
Python
Node.js
Kotlin
Swift
Dart
Java
Immagine
Python
Node.js
Kotlin
Swift
Dart
Java
Video
Python
Node.js
Kotlin
Java
Chat
Python
Node.js
Conchiglia
Kotlin
Swift
Dart
Java
Corpo della risposta
In caso di esito positivo, il corpo della risposta contiene un flusso di istanze GenerateContentResponse
.
GenerateContentResponse
Risposta del modello che supporta più candidati.
Nota sulle classificazioni della sicurezza e sul filtro dei contenuti. Sono riportate sia per la richiesta in GenerateContentResponse.prompt_feedback
che per ogni candidato in finishReason
e in safetyRatings
. Il contratto relativo all'API è il seguente: - vengono restituiti tutti i candidati richiesti o nessun candidato - nessun candidato viene restituito solo se si è verificato un problema con la richiesta (vedi promptFeedback
). I feedback relativi a ogni candidato vengono segnalati in data finishReason
e safetyRatings
.
Rappresentazione JSON |
---|
{ "candidates": [ { object ( |
candidates[]
object (Candidate
)
Risposte dei candidati del modello.
promptFeedback
object (PromptFeedback
)
Restituisce il feedback del prompt relativo ai filtri per i contenuti.
usageMetadata
object (UsageMetadata
)
Solo output. Metadati sulla riga delle richieste di generazione l'utilizzo dei token.
PromptFeedback
Un insieme di metadati dei feedback specificati dal prompt in GenerateContentRequest.content
.
Rappresentazione JSON |
---|
{ "blockReason": enum ( |
blockReason
enum (BlockReason
)
(Facoltativo) Se impostato, la richiesta è stata bloccata e non vengono restituiti candidati. Riformula il prompt.
safetyRatings[]
object (SafetyRating
)
Classificazioni per la sicurezza del prompt. Esiste al massimo una classificazione per categoria.
BlockReason
Specifica il motivo per cui la richiesta è stata bloccata.
Enum | |
---|---|
BLOCK_REASON_UNSPECIFIED |
Valore predefinito. Questo valore non è utilizzato. |
SAFETY |
Il prompt è stato bloccato per motivi di sicurezza. Puoi controllare safetyRatings per capire da quale categoria di sicurezza è stato bloccato. |
OTHER |
Il prompt è stato bloccato per motivi sconosciuti. |
UsageMetadata
Metadati sull'utilizzo dei token della richiesta di generazione.
Rappresentazione JSON |
---|
{ "promptTokenCount": integer, "cachedContentTokenCount": integer, "candidatesTokenCount": integer, "totalTokenCount": integer } |
promptTokenCount
integer
Numero di token nel prompt. Quando è impostata l'impostazione cacheContent, si tratta comunque delle dimensioni effettive totali del prompt. Ad esempio questo include il numero di token nei contenuti memorizzati nella cache.
cachedContentTokenCount
integer
Numero di token nella parte della richiesta memorizzata nella cache, ad esempio nei contenuti memorizzati nella cache.
candidatesTokenCount
integer
Numero totale di token tra i candidati generati.
totalTokenCount
integer
Conteggio totale dei token per la richiesta di generazione (prompt + candidati).
Candidato
- Rappresentazione JSON
- FinishReason
- GroundingAttribution
- AttributionSourceId
- GroundingPassageId
- SemanticRetrieverChunk
Un candidato per la risposta generato dal modello.
Rappresentazione JSON |
---|
{ "content": { object ( |
content
object (Content
)
Solo output. Contenuti generati restituiti dal modello.
finishReason
enum (FinishReason
)
(Facoltativo) Solo output. Il motivo per cui il modello ha smesso di generare token.
Se vuoto, il modello non ha smesso di generare i token.
safetyRatings[]
object (SafetyRating
)
Elenco di classificazioni per la sicurezza di un candidato a una risposta.
Esiste al massimo una classificazione per categoria.
citationMetadata
object (CitationMetadata
)
Solo output. Informazioni di citazione per il candidato generato dal modello.
Questo campo può essere compilato con informazioni sulle citazioni per qualsiasi testo incluso in content
. Questi sono passaggi che vengono "recitati" dal materiale protetto da copyright nei dati di addestramento degli LLM di base.
tokenCount
integer
Solo output. Conteggio dei token per questo candidato.
groundingAttributions[]
object (GroundingAttribution
)
Solo output. Informazioni sull'attribuzione per le fonti che hanno contribuito a una risposta con fondatezza.
Questo campo viene compilato per le chiamate GenerateAnswer
.
index
integer
Solo output. Indice del candidato nell'elenco dei candidati.
FinishReason
Definisce il motivo per cui il modello ha smesso di generare token.
Enum | |
---|---|
FINISH_REASON_UNSPECIFIED |
Valore predefinito. Questo valore non è utilizzato. |
STOP |
Punto di interruzione naturale del modello o sequenza di interruzione fornita. |
MAX_TOKENS |
È stato raggiunto il numero massimo di token specificato nella richiesta. |
SAFETY |
I contenuti dei candidati sono stati segnalati per motivi di sicurezza. |
RECITATION |
I contenuti dei candidati sono stati segnalati per motivi di recitazione. |
LANGUAGE |
I contenuti dei candidati sono stati segnalati per l'utilizzo di una lingua non supportata. |
OTHER |
Motivo sconosciuto. |
GroundingAttribution
Attribuzione di una fonte che ha contribuito a una risposta.
Rappresentazione JSON |
---|
{ "sourceId": { object ( |
sourceId
object (AttributionSourceId
)
Solo output. Identificatore della sorgente che contribuisce a questa attribuzione.
content
object (Content
)
Basandosi sui contenuti di origine che compongono questa attribuzione.
AttributionSourceId
Identificatore della sorgente che contribuisce a questa attribuzione.
Rappresentazione JSON |
---|
{ // Union field |
Campo unione source
.
source
può essere solo uno dei seguenti:
groundingPassage
object (GroundingPassageId
)
Identificatore per un passaggio in linea.
semanticRetrieverChunk
object (SemanticRetrieverChunk
)
Identificatore per un Chunk
recuperato tramite Semantic Retriever.
GroundingPassageId
Identificatore per una parte all'interno di un GroundingPassage
.
Rappresentazione JSON |
---|
{ "passageId": string, "partIndex": integer } |
passageId
string
Solo output. ID del passaggio corrispondente al valore GroundingPassage.id
di GenerateAnswerRequest
.
partIndex
integer
Solo output. Indice della parte all'interno del GroundingPassage.content
di GenerateAnswerRequest
.
SemanticRetrieverChunk
Identificatore di Chunk
recuperato tramite il Semantic Retriever specificato in GenerateAnswerRequest
utilizzando SemanticRetrieverConfig
.
Rappresentazione JSON |
---|
{ "source": string, "chunk": string } |
source
string
Solo output. Nome dell'origine corrispondente a SemanticRetrieverConfig.source
della richiesta. Esempio: corpora/123
o corpora/123/documents/abc
chunk
string
Solo output. Nome dell'evento Chunk
contenente il testo attribuito. Esempio: corpora/123/documents/abc/chunks/xyz
CitationMetadata
Una raccolta di attribuzioni della fonte per un contenuto.
Rappresentazione JSON |
---|
{
"citationSources": [
{
object ( |
citationSources[]
object (CitationSource
)
Citazioni di fonti per una risposta specifica.
CitationSource
Una citazione a una fonte per una parte di una risposta specifica.
Rappresentazione JSON |
---|
{ "startIndex": integer, "endIndex": integer, "uri": string, "license": string } |
startIndex
integer
(Facoltativo) Inizio del segmento della risposta attribuito a questa sorgente.
L'indice indica l'inizio del segmento, misurato in byte.
endIndex
integer
(Facoltativo) Fine del segmento attribuito (escluso).
uri
string
(Facoltativo) URI attribuito come origine per una parte del testo.
license
string
(Facoltativo) Licenza per il progetto GitHub attribuito come origine del segmento.
Le informazioni sulla licenza sono obbligatorie per le citazioni di codici.
GenerationConfig
Opzioni di configurazione per la generazione e gli output del modello. Non tutti i parametri possono essere configurabili per ogni modello.
Rappresentazione JSON |
---|
{
"stopSequences": [
string
],
"responseMimeType": string,
"responseSchema": {
object ( |
stopSequences[]
string
(Facoltativo) L'insieme di sequenze di caratteri (fino a 5) che interromperà la generazione dell'output. Se specificato, l'API si arresterà alla prima apparizione di una sequenza di interruzioni. La sequenza di interruzione non sarà inclusa nella risposta.
responseMimeType
string
(Facoltativo) Tipo MIME della risposta di output del testo candidato generato. Tipo MIME supportato: text/plain
: output di testo (predefinito). application/json
: risposta JSON nei candidati.
responseSchema
object (Schema
)
(Facoltativo) Schema della risposta di output del testo candidato generato quando il tipo MIME della risposta può avere uno schema. Lo schema può essere oggetti, primitive o array ed è un sottoinsieme dello schema OpenAPI.
Se impostato, è necessario impostare anche un valore responseMimeType compatibile. Tipi MIME compatibili: application/json
: schema per la risposta JSON.
candidateCount
integer
(Facoltativo) Numero di risposte generate da restituire.
Al momento, questo valore può essere impostato solo su 1. Se non viene configurato, il valore predefinito è 1.
maxOutputTokens
integer
(Facoltativo) Il numero massimo di token da includere in un candidato.
Nota: il valore predefinito varia a seconda del modello; controlla l'attributo Model.output_token_limit
di Model
restituito dalla funzione getModel
.
temperature
number
(Facoltativo) Controlla la casualità dell'output.
Nota: il valore predefinito varia a seconda del modello; controlla l'attributo Model.temperature
di Model
restituito dalla funzione getModel
.
I valori possono essere compresi tra [0,0, 2,0].
topP
number
(Facoltativo) La probabilità cumulativa massima dei token da considerare durante il campionamento.
Il modello utilizza il campionamento Top-K e del nucleo combinato.
I token vengono ordinati in base alle probabilità assegnate in modo che vengano presi in considerazione solo i token più probabili. Il campionamento top-k limita direttamente il numero massimo di token da considerare, mentre il campionamento Nucleo limita il numero di token in base alla probabilità cumulativa.
Nota: il valore predefinito varia a seconda del modello; controlla l'attributo Model.top_p
di Model
restituito dalla funzione getModel
.
topK
integer
(Facoltativo) Il numero massimo di token da considerare durante il campionamento.
I modelli utilizzano il campionamento del nucleo o il campionamento Top-k e del nucleo combinato. Il campionamento Top-k prende in considerazione l'insieme di topK
token più probabili. I modelli in esecuzione con il campionamento del nucleo non consentono l'impostazione di topK.
Nota: il valore predefinito varia a seconda del modello; controlla l'attributo Model.top_k
di Model
restituito dalla funzione getModel
. Il campo topK
vuoto in Model
indica che il modello non applica il campionamento top-k e non consente di impostare topK
sulle richieste.
HarmCategory
La categoria di una classificazione.
Queste categorie coprono vari tipi di danni che gli sviluppatori potrebbero voler adeguare.
Enum | |
---|---|
HARM_CATEGORY_UNSPECIFIED |
Categoria non specificata. |
HARM_CATEGORY_DEROGATORY |
Commenti negativi o dannosi che hanno come target l'identità e/o l'attributo protetto. |
HARM_CATEGORY_TOXICITY |
Contenuti scurrili, irrispettosi o volgari. |
HARM_CATEGORY_VIOLENCE |
Descrive gli scenari di violenza contro un individuo o un gruppo oppure descrizioni generali di spargimenti di sangue. |
HARM_CATEGORY_SEXUAL |
Riferimenti ad atti sessuali o ad altri contenuti osceni. |
HARM_CATEGORY_MEDICAL |
Promuove una consulenza medica non verificata. |
HARM_CATEGORY_DANGEROUS |
Contenuti pericolosi che promuovono, favoriscono o incoraggiano azioni dannose. |
HARM_CATEGORY_HARASSMENT |
Contenuti molesti. |
HARM_CATEGORY_HATE_SPEECH |
Contenuti e incitamento all'odio. |
HARM_CATEGORY_SEXUALLY_EXPLICIT |
Contenuti sessualmente espliciti. |
HARM_CATEGORY_DANGEROUS_CONTENT |
Contenuti pericolosi. |
SafetyRating
Valutazione della sicurezza di alcuni contenuti.
La valutazione di sicurezza contiene la categoria di danno e il livello di probabilità di danno in quella categoria per un determinato contenuto. I contenuti sono classificati per sicurezza in base a diverse categorie di danni e la probabilità della classificazione dei contenuti è inclusa qui.
Rappresentazione JSON |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
Obbligatorio. La categoria di questa classificazione.
probability
enum (HarmProbability
)
Obbligatorio. La probabilità di danni per questi contenuti.
blocked
boolean
I contenuti sono stati bloccati a causa della classificazione?
HarmProbability
La probabilità che un determinato contenuto sia dannoso.
Il sistema di classificazione dà la probabilità che i contenuti non siano sicuri. Ciò non indica la gravità del danno per un determinato contenuto.
Enum | |
---|---|
HARM_PROBABILITY_UNSPECIFIED |
La probabilità non è specificata. |
NEGLIGIBLE |
I contenuti hanno una probabilità trascurabile di non essere sicuri. |
LOW |
I contenuti hanno una bassa probabilità di non essere sicuri. |
MEDIUM |
I contenuti hanno una media probabilità di non essere sicuri. |
HIGH |
I contenuti hanno un'alta probabilità di non essere sicuri. |
SafetySetting
Impostazione di sicurezza, che influisce sul comportamento di blocco di sicurezza.
Il superamento di un'impostazione di sicurezza per una categoria cambia la probabilità consentita che i contenuti vengano bloccati.
Rappresentazione JSON |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
Obbligatorio. La categoria per questa impostazione.
threshold
enum (HarmBlockThreshold
)
Obbligatorio. Controlla la soglia di probabilità in cui il danno è bloccato.
HarmBlockThreshold
Blocco in base alla probabilità di danno specificata e oltre.
Enum | |
---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED |
La soglia non è specificata. |
BLOCK_LOW_AND_ABOVE |
I contenuti con NEGLIGIBLE saranno consentiti. |
BLOCK_MEDIUM_AND_ABOVE |
I contenuti con valori NEGLIGIBLE e LOW saranno consentiti. |
BLOCK_ONLY_HIGH |
Saranno consentiti i contenuti di tipo NEGLIGIBLE, LOW e MEDIUM. |
BLOCK_NONE |
Saranno consentiti tutti i contenuti. |