Informazioni di riferimento sulle API Assistants (anteprima)
Nota
- La ricerca di file può inserire fino a 10.000 file per assistente- 500 volte più di prima. È veloce, supporta query parallele tramite ricerche multithread e funzionalità avanzate di reranking e riscrittura delle query.
- L'archivio vettoriale è un nuovo oggetto nell'API. Dopo l'aggiunta di un file a un archivio vettoriale, l'analisi viene eseguita automaticamente, in blocchi e incorporati, pronta per la ricerca. Gli archivi vettoriali possono essere usati tra assistenti e thread, semplificando la gestione e la fatturazione dei file.
- È stato aggiunto il supporto per il
tool_choiceparametro che può essere usato per forzare l'uso di uno strumento specifico (ad esempio la ricerca di file, l'interprete di codice o una funzione) in una determinata esecuzione.
Questo articolo fornisce la documentazione di riferimento per Python e REST per la nuova API Assistants (anteprima). Nella guida introduttiva sono disponibili indicazioni dettagliate più dettagliate.
Creare un assistente
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview
Creare un assistente con un modello e istruzioni.
Testo della richiesta
| Nome | Digita | Obbligatorio | Descrizione |
|---|---|---|---|
| modello | string | Richiesto | Nome della distribuzione del modello da usare. |
| name | stringa o null | Facoltativo | Nome dell'assistente. La lunghezza massima consentita è di 256 caratteri. |
| description | stringa o null | Facoltativo | Descrizione dell'assistente. La lunghezza massima è di 512 caratteri. |
| istruzioni | stringa o null | Facoltativo | Istruzioni di sistema usate dall'assistente. La lunghezza massima è di 256.000 caratteri. |
| tools | array | Facoltativo | Il valore predefinito è []. Elenco degli strumenti abilitati nell'assistente. Può essere disponibile un massimo di 128 strumenti per assistente. Gli strumenti possono attualmente essere di tipi code_interpretero function. |
| file_ids | array | Facoltativo | Il valore predefinito è []. Elenco di ID file allegati a questo assistente. All'assistente possono essere associati al massimo 20 file. I file vengono ordinati in base alla data di creazione in ordine crescente. |
| metadata | mappa | Facoltativo | Set di 16 coppie chiave-valore che possono essere collegate a un oggetto . Ciò può essere utile per archiviare informazioni aggiuntive sull'oggetto in un formato strutturato. Le chiavi possono contenere un massimo di 64 caratteri e i valori possono contenere un massimo di 512 caratteri. |
| temperatura | number o null | Facoltativo | Assume il valore predefinito 1. Determina la temperatura di campionamento da usare, compresa tra 0 e 2. Valori più elevati come 0.8 renderanno l'output più casuale, mentre valori più bassi come 0.2 lo renderanno più mirato e deterministico. |
| top_p | number o null | Facoltativo | Assume il valore predefinito 1. Un'alternativa al campionamento con temperatura, denominata campionamento del nucleo, in cui il modello considera i risultati dei token con massa di probabilità top_p. Quindi 0,1 significa che vengono considerati solo i token che comprendono la massa di probabilità superiore del 10%. In genere è consigliabile modificare questo o la temperatura, ma non entrambi. |
| response_format | stringa o oggetto | Facoltativo | Specifica il formato che il modello deve restituire. Compatibile con GPT-4 Turbo e tutti i modelli GPT-3.5 Turbo da gpt-3.5-turbo-1106. L'impostazione di questo parametro su { "type": "json_object" } abilita la modalità JSON, che garantisce che il messaggio generato dal modello sia JSON valido. Importante, quando si usa la modalità JSON, è anche necessario indicare al modello di produrre json manualmente usando un messaggio di sistema o utente. Senza questa istruzione, il modello può generare un flusso inutile di spazi vuoti fino a quando la generazione non raggiunge il limite di token, con conseguente esecuzione prolungata e apparentemente "bloccata". Inoltre, il contenuto del messaggio può essere parzialmente tagliato se si usa finish_reason="length", che indica che la generazione è stata superata o la conversazione ha superato max_tokens la lunghezza massima del contesto. |
Valori restituiti
Oggetto assistente .
Esempio di richiesta di creazione assistente
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant = client.beta.assistants.create(
instructions="You are an AI assistant that can write code to help answer math questions",
model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name.
tools=[{"type": "code_interpreter"}]
)
Creare il file dell'assistente
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview
Creare un file di assistente allegando un File oggetto a un oggetto assistant.
Parametri del percorso
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
assistant_id |
stringa | Richiesto | ID dell'assistente a cui deve essere allegato il file. |
Testo della richiesta
| Nome | Digita | Obbligatorio | Descrizione |
|---|---|---|---|
| file_id | string | Richiesto | ID file (con purpose="assistants") che l'assistente deve usare. Utile per strumenti come code_interpreter che possono accedere ai file. |
Valori restituiti
Oggetto file assistente.
Esempio di richiesta di file di creazione assistente
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant_file = client.beta.assistants.files.create(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(assistant_file)
Elencare gli assistenti
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview
Restituisce un elenco di tutti gli assistenti.
Parametri di query
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
limit |
integer | Facoltativo | Limite al numero di oggetti da restituire. Il limite può variare tra 1 e 100 e il valore predefinito è 20. |
order |
string | Facoltativo - Impostazione predefinita di desc | Ordinare in base al timestamp created_at degli oggetti. asc per ordine crescente e desc per l'ordine decrescente. |
after |
string | Facoltativo | Cursore da usare nella paginazione. after è un ID oggetto che definisce la posizione nell'elenco. Ad esempio, se si effettua una richiesta di elenco e si ricevono 100 oggetti, terminando con obj_foo, la chiamata successiva può includere after=obj_foo per recuperare la pagina successiva dell'elenco. |
before |
string | Facoltativo | Cursore da usare nella paginazione. before è un ID oggetto che definisce la posizione nell'elenco. Ad esempio, se si effettua una richiesta di elenco e si ricevono 100 oggetti, terminando con obj_foo, la chiamata successiva può includere before=obj_foo per recuperare la pagina precedente dell'elenco. |
Valori restituiti
Elenco di oggetti assistente
Assistenti elenco di esempio
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistants = client.beta.assistants.list(
order="desc",
limit="20",
)
print(my_assistants.data)
Elencare i file dell'assistente
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview
Restituisce un elenco di file di assistente.
Parametri del percorso
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
| assistant_id | string | Richiesto | ID dell'assistente a cui appartiene il file. |
Parametri di query
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
limit |
integer | Facoltativo | Limite al numero di oggetti da restituire. Il limite può variare tra 1 e 100 e il valore predefinito è 20. |
order |
string | Facoltativo - Impostazione predefinita di desc | Ordinare in base al timestamp created_at degli oggetti. asc per ordine crescente e desc per l'ordine decrescente. |
after |
string | Facoltativo | Cursore da usare nella paginazione. after è un ID oggetto che definisce la posizione nell'elenco. Ad esempio, se si effettua una richiesta di elenco e si ricevono 100 oggetti, terminando con obj_foo, la chiamata successiva può includere after=obj_foo per recuperare la pagina successiva dell'elenco. |
before |
string | Facoltativo | Cursore da usare nella paginazione. before è un ID oggetto che definisce la posizione nell'elenco. Ad esempio, se si effettua una richiesta di elenco e si ricevono 100 oggetti, terminando con obj_foo, la chiamata successiva può includere before=obj_foo per recuperare la pagina precedente dell'elenco. |
Valori restituiti
Elenco di oggetti file assistente
File di assistente elenco di esempio
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant_files = client.beta.assistants.files.list(
assistant_id="asst_abc123"
)
print(assistant_files)
Recupera assistente
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview
Recupera un assistente.
Parametri del percorso
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
assistant_id |
stringa | Richiesto | ID dell'assistente da recuperare. |
Resi
Oggetto assistente corrispondente all'ID specificato.
Esempio di assistente recupero
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)
Recuperare il file dell'assistente
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
Recupera un file assistant.
Parametri del percorso
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
| assistant_id | string | Richiesto | ID dell'assistente a cui appartiene il file. |
| file_id | string | Richiesto | ID del file che si sta ottenendo |
Valori restituiti
Oggetto file assistant corrispondente all'ID specificato
Esempio di recupero del file assistente
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant_file = client.beta.assistants.files.retrieve(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(assistant_file)
Modifica assistente
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview
Modifica un assistente.
Parametri del percorso
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
| assistant_id | string | Richiesto | ID dell'assistente a cui appartiene il file. |
Corpo della richiesta
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
model |
Facoltativo | Nome della distribuzione del modello da usare. | |
name |
stringa o null | Facoltativo | Nome dell'assistente. La lunghezza massima consentita è di 256 caratteri. |
description |
stringa o null | Facoltativo | Descrizione dell'assistente. La lunghezza massima è di 512 caratteri. |
instructions |
stringa o null | Facoltativo | Istruzioni di sistema usate dall'assistente. La lunghezza massima è di 32768 caratteri. |
tools |
array | Facoltativo | Il valore predefinito è []. Elenco degli strumenti abilitati nell'assistente. Può essere disponibile un massimo di 128 strumenti per assistente. Gli strumenti possono essere di tipi code_interpreter o funzione. |
file_ids |
array | Facoltativo | Il valore predefinito è []. Elenco di ID file allegati a questo assistente. All'assistente possono essere associati al massimo 20 file. I file vengono ordinati in base alla data di creazione in ordine crescente. Se un file è stato allegato in precedenza all'elenco ma non viene visualizzato nell'elenco, verrà eliminato dall'assistente. |
metadata |
mappa | Facoltativo | Set di 16 coppie chiave-valore che possono essere collegate a un oggetto . Ciò può essere utile per archiviare informazioni aggiuntive sull'oggetto in un formato strutturato. Le chiavi possono contenere un massimo di 64 caratteri e i valori possono contenere un massimo di 512 caratteri. |
Resi
Oggetto assistente modificato.
Assistente modifica di esempio
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_updated_assistant = client.beta.assistants.update(
"asst_abc123",
instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
name="HR Helper",
tools=[{"type": "code-interpreter"}],
model="gpt-4", #model = model deployment name
file_ids=["assistant-abc123", "assistant-abc456"],
)
print(my_updated_assistant)
Elimina assistente
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview
Eliminare un assistente.
Parametri del percorso
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
assistant_id |
stringa | Richiesto | ID dell'assistente a cui appartiene il file. |
Resi
Stato di eliminazione.
Esempio di assistente eliminazione
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
response = client.beta.assistants.delete("asst_abc123")
print(response)
Eliminare il file dell'assistente
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
Eliminare un file di assistente.
Parametri del percorso
| Parametro | Type | Obbligatorio | Descrizione |
|---|---|---|---|
assistant_id |
stringa | Richiesto | ID dell'assistente a cui appartiene il file. |
file_id |
string | Richiesto | ID del file da eliminare |
Resi
Stato di eliminazione dei file
Esempio di file di eliminazione assistente
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
deleted_assistant_file = client.beta.assistants.files.delete(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(deleted_assistant_file)
Informazioni di riferimento sulle API per il caricamento di file
Gli assistenti usano la stessa API per il caricamento di file come ottimizzazione. Quando si carica un file è necessario specificare un valore appropriato per il parametro scopo.
Oggetto Assistant
| Campo | Tipo | Descrzione |
|---|---|---|
id |
stringa | Identificatore a cui è possibile fare riferimento negli endpoint API. |
object |
string | Tipo di oggetto, che è sempre assistente. |
created_at |
integer | Timestamp Unix (in secondi) per il momento in cui è stato creato l'assistente. |
name |
stringa o null | Nome dell'assistente. La lunghezza massima consentita è di 256 caratteri. |
description |
stringa o null | Descrizione dell'assistente. La lunghezza massima è di 512 caratteri. |
model |
string | Nome del nome della distribuzione del modello da usare. |
instructions |
stringa o null | Istruzioni di sistema usate dall'assistente. La lunghezza massima è di 32768 caratteri. |
tools |
array | Elenco di strumenti abilitati nell'assistente. Può essere disponibile un massimo di 128 strumenti per assistente. Gli strumenti possono essere di tipi code_interpreter o funzione. |
file_ids |
array | Elenco di ID file allegati a questo assistente. All'assistente possono essere associati al massimo 20 file. I file vengono ordinati in base alla data di creazione in ordine crescente. |
metadata |
mappa | Set di 16 coppie chiave-valore che possono essere collegate a un oggetto . Ciò può essere utile per archiviare informazioni aggiuntive sull'oggetto in un formato strutturato. Le chiavi possono contenere un massimo di 64 caratteri e i valori possono contenere un massimo di 512 caratteri. |
Oggetto file assistente
| Campo | Tipo | Descrzione |
|---|---|---|
id |
stringa | Identificatore a cui è possibile fare riferimento negli endpoint API. |
object |
string | Tipo di oggetto, che è sempre assistant.file |
created_at |
integer | Timestamp Unix (in secondi) per il momento in cui è stato creato il file assistente. |
assistant_id |
string | ID assistente a cui è allegato il file. |