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.

tipi di response_format

string

auto è il valore predefinito.

object

Valori possibili type : text, json_object, json_schema.

json_schema

Nome Tipo Descrizione Default Obbligatoria/Facoltativa
description string Descrizione del formato di risposta, usato dal modello per determinare come rispondere nel formato. Facoltativo
name string Nome del formato della risposta. Deve essere a-z, A-Z, 0-9 o contenere caratteri di sottolineatura e trattini, con una lunghezza massima di 64 caratteri. Richiesto
schema oggetto Schema per il formato di risposta, descritto come oggetto Schema JSON. Facoltativo
strict booleano o null Indica se abilitare una rigorosa conformità allo schema durante la generazione dell'output. Se impostato su true, il modello seguirà sempre lo schema esatto definito nel campo schema. Solo un subset di schema JSON è supportato quando strict è true. false Facoltativo

Proprietà tool_resources

code_interpreter

Nome Tipo Descrizione Default
file_ids array Elenco di ID file resi disponibili allo strumento code_interpreter. Allo strumento possono essere associati al massimo 20 file. []

file_search

Nome Tipo Descrizione Obbligatorio/facoltativo
vector_store_ids array L’archivio vettoriale collegato a questo thread. Può essere presente un massimo di 1 archivio vettoriale collegato al thread. Facoltativo
vector_stores array Helper per creare un archivio vettoriale con file_ids e collegarlo a questo thread. Può essere presente un massimo di 1 archivio vettoriale collegato al thread. Facoltativo

vector_stores

Nome Tipo Descrizione Obbligatorio/facoltativo
file_ids array Elenco di ID file da aggiungere all'archivio vettoriale. Può essere presente un massimo di 10000 file in un archivio vettoriale. Facoltativo
chunking_strategy oggetto Strategia di suddivisione in blocchi usata per suddividere i file. Se non impostato, userà la strategia automatica. Facoltativo
metadata mappa Set di 16 coppie chiave-valore che possono essere collegate a un archivio vettoriale. Può essere utile per archiviare informazioni aggiuntive sull'archivio vettoriale in un formato strutturato. Le chiavi possono essere lunghe al massimo 64 caratteri, mentre i valori al massimo 512 caratteri. Facoltativo

chunking_strategy

Nome Tipo Descrizione Obbligatoria/facoltativa
Auto Chunking Strategy oggetto Strategia predefinita. Attualmente, questa strategia usa un max_chunk_size_tokens di 800 e chunk_overlap_tokens di 400. type è sempre auto Richiesto
Static Chunking Strategy oggetto type Sempre static Richiesto

Strategia di suddivisione in blocchi statici

Nome Tipo Descrizione Obbligatorio/facoltativo
max_chunk_size_tokens integer Numero massimo di token in ogni blocco. Il valore predefinito è 800. Il valore minimo è 100 e il valore massimo è 4096. Richiesto
chunk_overlap_tokens integer Numero di token che si sovrappongono tra blocchi. Il valore predefinito è 400. Notare che la sovrapposizione non deve superare la metà di max_chunk_size_tokens. Richiesto

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.