Condividi tramite

Informazioni di riferimento sull'API Assistenti (anteprima)

  • Articolo

Nota

  • Ricerca file può inserire fino a 10.000 file per assistente, 500 volte più di prima. È veloce, supporta query parallele tramite ricerche multithread e include la riclassificazione avanzata e la riscrittura di query.
    • L’archivio di vettori è un nuovo oggetto nell’API. Dopo l’aggiunta a un archivio di vettori, un file viene analizzato, suddiviso in blocchi, incorporato e preparato per essere sottoposto a ricerca. Gli archivi di vettori possono essere usati in diversi assistenti e thread, semplificando quindi la gestione dei file e la fatturazione.
  • È stato aggiunto il supporto per il parametro tool_choice, che può essere usato per imporre l’uso di uno strumento specifico, ad esempio ricerca file, 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 Assistenti (anteprima) Nella guida introduttiva sono disponibili indicazioni 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 Il nome dell’argomento. 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 di strumenti abilitati nell'assistente. Può essere disponibile un massimo di 128 strumenti per assistente. Gli strumenti possono attualmente essere di tipi code_interpreter o function. Una descrizione di function può avere un massimo di 1.024 caratteri.
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 essere lunghe al massimo 64 caratteri, mentre i valori al massimo 512 caratteri.
temperatura numero 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 numero 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 successivi a 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, è necessario anche indicare al modello di produrre JSON manualmente utilizzando un messaggio di sistema o utente. Senza questa istruzione, il modello potrebbe generare un flusso inutile di spazi vuoti fino a quando la generazione non raggiunge il limite di token, causando una richiesta a esecuzione prolungata e apparentemente "bloccata". In aggiunta, il contenuto del messaggio può essere parzialmente tagliato se si utilizza finish_reason="length", che indica che la generazione ha superato max_tokens o la conversazione ha superato la lunghezza massima del contesto.
tool_resources oggetto Facoltativo Set di risorse usate dagli strumenti dell'assistente. Le risorse sono specifiche del tipo di strumento. Ad esempio, lo strumento code_interpreter richiede un elenco di ID di file, mentre lo strumento file_search richiede un elenco di ID archivio vettoriali.

Valori restituiti

Un 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-08-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"}]
)

Elenca 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 - Il valore predefinito è desc Ordinamento in base al timestamp created_at degli oggetti. asc per ordine crescente e desc per l'ordine decrescente.
after string Facoltativo Cursore da usare nell'impaginazione. after è un ID oggetto che definisce la posizione nell'elenco. Ad esempio, se si effettua una richiesta di elenco e si ricevono 100 oggetti, che terminano con obj_foo, la chiamata successiva può includere after=obj_foo per recuperare la pagina successiva dell'elenco.
before string Facoltativo Cursore da usare nell'impaginazione. before è un ID oggetto che definisce la posizione nell'elenco. Ad esempio, se si effettua una richiesta di elenco e si ricevono 100 oggetti, che terminano con obj_foo, la chiamata successiva può includere before=obj_foo per recuperare la pagina precedente dell'elenco.

Valori restituiti

Elenco di oggetti assistente

Esempio di Elenca assistenti

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

Recupera assistente

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-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 Recupera assistente

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

Modifica assistente

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Recupera 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 Il nome dell’argomento. 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 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. Una descrizione di function può avere un massimo di 1.024 caratteri.
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 essere lunghe al massimo 64 caratteri, mentre i valori al massimo 512 caratteri.
temperature numero 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 numero 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 successivi a 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, è necessario anche indicare al modello di produrre JSON manualmente utilizzando un messaggio di sistema o utente. Senza questa istruzione, il modello potrebbe generare un flusso inutile di spazi vuoti fino a quando la generazione non raggiunge il limite di token, causando una richiesta a esecuzione prolungata e apparentemente "bloccata". In aggiunta, il contenuto del messaggio può essere parzialmente tagliato se si utilizza finish_reason="length", che indica che la generazione ha superato max_tokens o la conversazione ha superato la lunghezza massima del contesto.
tool_resources oggetto Facoltativo Set di risorse usate dagli strumenti dell'assistente. Le risorse sono specifiche del tipo di strumento. Ad esempio, lo strumento code_interpreter richiede un elenco di ID di file, mentre lo strumento file_search richiede un elenco di ID archivio vettoriali.

Resi

Oggetto assistente modificato.

Esempio di Modifica assistente

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-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
)

print(my_updated_assistant)

Elimina assistente

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Elimina 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 Elimina assistente

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

Riferimento 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 assistente

Campo Tipo Descrizione
id stringa Identificatore a cui è possibile fare riferimento negli endpoint API.
object string Il tipo di oggetto, che è sempre assistente.
created_at integer Timestamp Unix (in secondi) di quando è stato creato l’assistente.
name stringa o null Il nome dell’argomento. 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. Una descrizione di function può avere un massimo di 1.024 caratteri.
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 essere lunghe al massimo 64 caratteri, mentre i valori al massimo 512 caratteri.
temperature numero o null 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 numero o null 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 Specifica il formato che il modello deve restituire. Compatibile con GPT-4 Turbo e tutti i modelli GPT-3.5 Turbo successivi a 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, è necessario anche indicare al modello di produrre JSON manualmente utilizzando un messaggio di sistema o utente. Senza questa istruzione, il modello potrebbe generare un flusso inutile di spazi vuoti fino a quando la generazione non raggiunge il limite di token, causando una richiesta a esecuzione prolungata e apparentemente "bloccata". In aggiunta, il contenuto del messaggio può essere parzialmente tagliato se si utilizza finish_reason="length", che indica che la generazione ha superato max_tokens o la conversazione ha superato la lunghezza massima del contesto.
tool_resources oggetto Set di risorse usate dagli strumenti dell'assistente. Le risorse sono specifiche del tipo di strumento. Ad esempio, lo strumento code_interpreter richiede un elenco di ID di file, mentre lo strumento file_search richiede un elenco di ID archivio vettoriali.