Referência de mensagens da API de Assistentes (Versão prévia)

  • Artigo

Observação

  • A pesquisa de arquivos pode ingerir até 10.000 arquivos por assistente – 500 vezes mais do que antes. Ela é rápida, dá suporte a consultas paralelas por meio de pesquisas com vários threads e recursos aprimorados de reclassificação e reescrita de consulta.
    • O repositório de vetores é um novo objeto na API. Depois que um arquivo é adicionado a um repositório de vetores, ele é analisado automaticamente, em partes e inserido, pronto para ser pesquisado. Os repositórios de vetores podem ser usados entre assistentes e threads, simplificando o gerenciamento de arquivos e a cobrança.
  • Adicionamos suporte para o parâmetro tool_choice que pode ser usado para forçar o uso de uma ferramenta específica (como pesquisa de arquivo, interpretador de código ou uma função) em uma execução específica.

Este artigo fornece documentação de referência para Python e REST para a nova API de Assistentes (Versão prévia). Diretrizes passo a passo mais detalhadas são fornecidas no guia de introdução.

Criar mensagem

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

Crie uma mensagem.

Parâmetro de caminho

Parâmetro Type Obrigatória Descrição
thread_id string Obrigatório A ID do thread para o qual criar uma mensagem.

Corpo da solicitação

Nome Digitar Obrigatória Descrição
role string Obrigatório A função da entidade que está criando a mensagem. Pode ser user ou assistant. user indica que a mensagem foi enviada por um usuário real e, geralmente, deve ser usada para representar mensagens geradas por usuários. assistant indica que a mensagem foi gerada pelo assistente. Use esse valor para inserir mensagens do assistente na conversa.
content string Obrigatório O conteúdo da mensagem.
file_ids matriz Opcional Uma lista de IDs de arquivo que a mensagem deve usar. Pode haver no máximo 10 arquivos anexados a uma mensagem. Útil para ferramentas como recuperação e code_interpreter que podem acessar e usar arquivos.
metadata map Opcional Conjunto de 16 pares chave-valor que podem ser anexados a um objeto. Isso pode ser útil para armazenar informações adicionais sobre o objeto em um formato estruturado. As chaves podem ter no máximo 64 caracteres e os valores podem ter no máximo 512 caracteres.

Retornos

Um objeto de mensagem.

Exemplo de solicitação de criação de mensagem

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)

Listar mensagens

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

Retorna uma lista de mensagens para um determinado thread.

Parâmetros de caminho

Parâmetro Type Obrigatória Descrição
thread_id string Obrigatório A ID do thread ao qual as mensagens pertencem.

Parâmetros de consulta

Nome Digitar Obrigatória Descrição
limit Número inteiro Opcional – Os padrões para 20 Um limite no número de objetos a serem retornados. "Limit" pode variar entre 1 e 100 e o padrão é 20.
order string Opcional – Os padrões para desc Ordem de classificação pelo carimbo de data/hora de created_at dos objetos. "asc" para ordem crescente e "desc" para ordem decrescente.
after string Opcional Um cursor para uso na paginação. "after" é uma ID de objeto que define seu lugar na lista. Por exemplo, caso faça uma solicitação de lista e receba 100 objetos, terminando com obj_foo, sua chamada subsequente poderá incluir after=obj_foo, para buscar a próxima página da lista.
before string Opcional Um cursor para uso na paginação. "before" é uma ID de objeto que define seu lugar na lista. Por exemplo, caso faça uma solicitação de lista e receba 100 objetos, terminando com obj_foo, sua chamada subsequente poderá incluir before=obj_foo, para buscar a página anterior da lista.

Retornos

Uma lista de objetos de mensagem.

Exemplo de solicitação de mensagens de lista

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)

Recuperar mensagem

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

Recupera um arquivo de mensagem.

Parâmetros de caminho

Parâmetro Type Obrigatória Descrição
thread_id string Obrigatório A ID do thread à qual a mensagem pertence.
message_id string Obrigatório A ID da mensagem a ser recuperada.

Retornos

O objeto de mensagem que corresponde à ID especificada.

Exemplo de solicitação de recuperação de mensagem

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)

Modificar mensagem

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

Modifica uma mensagem.

Parâmetros de caminho

Parâmetro Type Obrigatória Descrição
thread_id string Obrigatório A ID do thread à qual a mensagem pertence.
message_id string Obrigatório A ID da mensagem a ser modificada.

Corpo da solicitação

Parâmetro Type Obrigatória Descrição
metadata map Opcional Conjunto de 16 pares chave-valor que podem ser anexados a um objeto. Isso pode ser útil para armazenar informações adicionais sobre o objeto em um formato estruturado. As chaves podem ter no máximo 64 caracteres e os valores podem ter no máximo 512 caracteres.

Retornos

O objeto de mensagem modificado.

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)

Excluir mensagem

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

Exclui uma mensagem.

Parâmetros de caminho

Parâmetro Type Obrigatória Descrição
thread_id string Obrigatório A ID do thread à qual a mensagem pertence.
message_id string Obrigatório A ID da mensagem a ser modificada.

Devoluções

O status de exclusão do objeto de mensagem.

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)

Objeto Message

Representa uma mensagem dentro de um thread.

Nome Tipo Descrição
id string O identificador, que pode ser referenciado em pontos de extremidade de API.
object string O tipo de objeto, que é sempre thread.message.
created_at Número inteiro O carimbo de data/hora do Unix (em segundos), para quando a mensagem foi criada.
thread_id string A ID do thread à qual essa mensagem pertence.
role string A entidade que produziu a mensagem. Uma opção entre user ou assistant.
content matriz O conteúdo da mensagem na matriz de texto e/ou imagens.
assistant_id cadeia de caracteres ou nulo Se aplicável, a ID do assistente que criou esta mensagem.
run_id cadeia de caracteres ou nulo Se aplicável, a ID da execução associada à criação dessa mensagem.
file_ids matriz Uma lista de IDs de arquivo que o assistente deve usar. Útil para ferramentas como recuperação e code_interpreter que podem acessar arquivos. No máximo 10 arquivos podem ser anexados a uma mensagem.
metadata map Conjunto de 16 pares chave-valor que podem ser anexados a um objeto. Isso pode ser útil para armazenar informações adicionais sobre o objeto em um formato estruturado. As chaves podem ter no máximo 64 caracteres e os valores podem ter no máximo 512 caracteres.