Informazioni di riferimento sull'API Assistenti (anteprima)

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-08-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.
attachments	array	Facoltativo	Elenco di file allegati al messaggio e gli strumenti a cui devono essere aggiunti.
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

Python 1.x

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

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

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "role": "user",
      "content": "How does AI work? Explain it in simple terms."
    }' 

Elenca messaggi

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-08-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.
run_id	string	Facoltativo	Filtrare i messaggi per ID esecuzione che li ha generati.
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

Python 1.x

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

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

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' 

Recupera messaggio

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-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

Python 1.x

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)

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' 

Modifica messaggio

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-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.

Python 1.x

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

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

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-01-preview
``` \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "metadata": {
        "modified": "true",
        "user": "abc123"
      }
    }'  
   

Messaggio di eliminazione

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-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.

Python 1.x

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

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

REST

curl -x DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

Oggetto Messagge

Rappresenta un messaggio all'interno di un thread.

Nome	Tipo	Descrizione
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.