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.

Crea messaggio

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-05-01-preview

Creare un messaggio.

Parametro percorso

Parametro Type Obbligatorio Descrizione
thread_id stringa Richiesto ID del thread per cui creare un messaggio.

Testo della richiesta

Nome Digita Obbligatorio Descrizione
role stringa Richiesto Ruolo dell'entità che crea il messaggio. Può essere user o assistant. user indica che il messaggio viene inviato da un utente effettivo e deve essere usato nella maggior parte dei casi per rappresentare i messaggi generati dall'utente. assistant indica che il messaggio viene generato dall'assistente. Usare questo valore per inserire messaggi dall'assistente nella conversazione.
content string Richiesto Contenuto del messaggio.
file_ids array Facoltativo Elenco di ID file che il messaggio deve usare. È ammesso un massimo di 10 file collegati a un messaggio. Utile per strumenti come il recupero e code_interpreter che possono accedere e usare file.
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.

Valori restituiti

Un oggetto messaggio.

Esempio di creazione di una richiesta di messaggio

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")
    )

thread_message = client.beta.threads.messages.create(
  "thread_abc123",
  role="user",
  content="How does AI work? Explain it in simple terms.",
)
print(thread_message)

Elenca messaggi

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-05-01-preview

Restituisce un elenco di messaggi per un determinato thread.

Parametri del percorso

Parametro Type Obbligatorio Descrizione
thread_id stringa Richiesto ID del thread a cui appartengono i messaggi.

Parametri della query

Nome Digita Obbligatorio Descrizione
limit integer Facoltativo - Il valore predefinito è 20 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 messaggio.

Esempio di richiesta di elenco di messaggi

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")
    )

thread_messages = client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)

Recupera messaggio

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-05-01-preview

Recupera un file di messaggio.

Parametri del percorso

Parametro Type Obbligatorio Descrizione
thread_id stringa Richiesto ID del thread a cui appartiene il messaggio.
message_id string Richiesto ID del messaggio da recuperare.

Valori restituiti

Oggetto messaggio corrispondente all'ID specificato.

Esempio di richiesta di recupero messaggi

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")
    )

message = client.beta.threads.messages.retrieve(
  message_id="msg_abc123",
  thread_id="thread_abc123",
)
print(message)

Modifica messaggio

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-05-01-preview

Modifica un messaggio.

Parametri del percorso

Parametro Type Obbligatorio Descrizione
thread_id stringa Richiesto ID del thread a cui appartiene il messaggio.
message_id string Richiesto ID del messaggio da modificare.

Testo della richiesta

Parametro Type Obbligatorio Descrizione
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.

Valori restituiti

Oggetto del messaggio modificato.

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")
    )

message = client.beta.threads.messages.update(
  message_id="msg_abc12",
  thread_id="thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123",
  },
)
print(message)

Messaggio di eliminazione

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-05-01-preview

Elimina un messaggio.

Parametri del percorso

Parametro Type Obbligatorio Descrizione
thread_id stringa Richiesto ID del thread a cui appartiene il messaggio.
message_id string Richiesto ID del messaggio da modificare.

Valori restituiti

Stato di eliminazione dell'oggetto messaggio.

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")
    )

deleted_message = client.beta.threads.messages.delete(
  message_id="msg_abc12",
  thread_id="thread_abc123",
)
print(deleted_message)

Oggetto Messagge

Rappresenta un messaggio all'interno di un thread.

Nome Tipo Descrzione
id stringa Identificatore a cui è possibile fare riferimento negli endpoint API.
object string Tipo di oggetto, che è sempre thread.message.
created_at integer Timestamp Unix (in secondi) di quando è stato creato il messaggio.
thread_id string L’ID del thread a cui appartiene questo messaggio.
role string Entità che ha generato il messaggio. Uno tra user o assistant.
content array Contenuto del messaggio in matrice di testo e/o immagini.
assistant_id stringa o null Se applicabile, l'ID dell'assistente che ha creato il messaggio.
run_id stringa o null Se applicabile, l'ID dell'esecuzione associata alla creazione di questo messaggio.
file_ids array Elenco di ID file che l'assistente deve usare. Utile per strumenti come il recupero e code_interpreter che possono accedere ai file. È possibile collegare un massimo di 10 file a un messaggio.
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.