Referência 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 um assistente

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

Crie um assistente com um modelo e instruções.

Corpo da solicitação

Nome Digitar Obrigatória Descrição
modelo string Obrigatório Nome da implantação de modelo a ser usado.
name cadeia de caracteres ou nulo Opcional O nome do assistente. O tamanho máximo é de 256 caracteres.
descrição cadeia de caracteres ou nulo Opcional A descrição do assistente. O tamanho máximo é de 512 caracteres.
instruções cadeia de caracteres ou nulo Opcional As instruções do sistema que o assistente usa. O tamanho máximo é de 256.000 caracteres.
manuais matriz Opcional Usa [] como padrão. Uma lista de ferramentas habilitadas no assistente. Pode haver no máximo 128 ferramentas por assistente. Atualmente, as ferramentas podem ser de tipos code_interpreter ou function. Uma descrição de function pode ter, no máximo, 1.024 caracteres.
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.
temperatura número ou nulo Opcional O valor padrão é 1. Qual temperatura de amostragem usar, entre 0 e 2. Valores mais altos, como 0,8, tornarão a saída mais aleatória, enquanto valores mais baixos como 0,2 a tornarão mais focada e determinística.
top_p número ou nulo Opcional O valor padrão é 1. Uma alternativa à amostragem com temperatura, chamada de amostragem de núcleo, onde o modelo considera os resultados dos tokens com massa de probabilidade top_p. Portanto, 0,1 significa que apenas os tokens que compõem a massa de probabilidade de 10% do topo são considerados. Geralmente, é recomendável alterar este ou a temperatura, mas não ambos.
response_format cadeia de caracteres ou objeto Opcional Especifica o formato que o modelo precisa gerar. Compatível com GPT-4 Turbo e todos os modelos GPT-3.5 Turbo a partir do gpt-3.5-turbo-1106. Definir esse parâmetro para { "type": "json_object" } habilita o modo JSON, o que garante que a mensagem gerada pelo modelo seja um JSON válido. É importante ressaltar que, ao usar o modo JSON, você também precisa instruir o modelo a produzir JSON por conta própria usando um sistema ou mensagem de usuário. Sem essa instrução, o modelo pode gerar um fluxo sem fim de espaço em branco até que a geração atinja o limite de token, resultando em uma solicitação de execução longa e aparentemente "paralisada". Além disso, o conteúdo da mensagem pode ser parcialmente cortado se você usa finish_reason="length", o que indica que a geração excedeu max_tokens ou a conversa excedeu o comprimento máximo do contexto.
tool_resources objeto Opcional Um conjunto de recursos que são usados pelas ferramentas do assistente. Os recursos são específicos para o tipo de ferramenta. Por exemplo, a ferramenta code_interpreter requer uma lista de IDs de arquivo, enquanto a ferramenta file_search requer uma lista de IDs do repositório de vetores.

Devoluções

Um objeto de assistente.

Exemplo de solicitação de assistente de criação

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

Listar assistentes

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

Retorna uma lista de todos os assistentes.

Parâmetros de consulta

Parâmetro Type Obrigatória Descrição
limit Número inteiro Opcional 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 assistente

Exemplo de assistentes de lista

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)

Assistente de recuperação

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

Recupera um assistente.

Parâmetros de caminho

Parâmetro Type Obrigatória Descrição
assistant_id string Obrigatório A ID do assistente a ser recuperado.

Retorna

O objeto de assistente que corresponde à ID especificada.

Exemplo de assistente de recuperação

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)

Assistente de modificação

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

Modifica um assistente.

Parâmetros de caminho

Parâmetro Type Obrigatória Descrição
assistant_id string Obrigatório A ID do assistente à qual o arquivo pertence.

Corpo da solicitação

Parâmetro Type Obrigatória Descrição
model Opcional O nome de implantação do modelo a ser usado.
name cadeia de caracteres ou nulo Opcional O nome do assistente. O tamanho máximo é de 256 caracteres.
description cadeia de caracteres ou nulo Opcional A descrição do assistente. O tamanho máximo é de 512 caracteres.
instructions cadeia de caracteres ou nulo Opcional As instruções do sistema que o assistente usa. O tamanho máximo é de 32.768 caracteres.
tools matriz Opcional Usa [] como padrão. Uma lista de ferramentas habilitadas no assistente. Pode haver no máximo 128 ferramentas por assistente. As ferramentas podem ser de tipos code_interpreter ou função. Uma descrição de function pode ter, no máximo, 1.024 caracteres.
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.
temperature número ou nulo Opcional O valor padrão é 1. Qual temperatura de amostragem usar, entre 0 e 2. Valores mais altos, como 0,8, tornarão a saída mais aleatória, enquanto valores mais baixos como 0,2 a tornarão mais focada e determinística.
top_p número ou nulo Opcional O valor padrão é 1. Uma alternativa à amostragem com temperatura, chamada de amostragem de núcleo, onde o modelo considera os resultados dos tokens com massa de probabilidade top_p. Portanto, 0,1 significa que apenas os tokens que compõem a massa de probabilidade de 10% do topo são considerados. Geralmente, é recomendável alterar este ou a temperatura, mas não ambos.
response_format cadeia de caracteres ou objeto Opcional Especifica o formato que o modelo precisa gerar. Compatível com GPT-4 Turbo e todos os modelos GPT-3.5 Turbo a partir do gpt-3.5-turbo-1106. Definir esse parâmetro para { "type": "json_object" } habilita o modo JSON, o que garante que a mensagem gerada pelo modelo seja um JSON válido. É importante ressaltar que, ao usar o modo JSON, você também precisa instruir o modelo a produzir JSON por conta própria usando um sistema ou mensagem de usuário. Sem essa instrução, o modelo pode gerar um fluxo sem fim de espaço em branco até que a geração atinja o limite de token, resultando em uma solicitação de execução longa e aparentemente "paralisada". Além disso, o conteúdo da mensagem pode ser parcialmente cortado se você usa finish_reason="length", o que indica que a geração excedeu max_tokens ou a conversa excedeu o comprimento máximo do contexto.
tool_resources objeto Opcional Um conjunto de recursos que são usados pelas ferramentas do assistente. Os recursos são específicos para o tipo de ferramenta. Por exemplo, a ferramenta code_interpreter requer uma lista de IDs de arquivo, enquanto a ferramenta file_search requer uma lista de IDs do repositório de vetores.

Retorna

O objeto de assistente modificado.

Exemplo de assistente de modificação

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)

Excluir assistente

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

Excluir um assistente.

Parâmetros de caminho

Parâmetro Type Obrigatória Descrição
assistant_id string Obrigatório A ID do assistente à qual o arquivo pertence.

Retorna

Status da exclusão.

Exemplo de assistente de exclusão

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)

Referência da API de upload de arquivo

Os assistentes usam a mesma API para upload de arquivo que ajuste fino. Ao carregar um arquivo, você precisa especificar um valor apropriado para o parâmetro de finalidade.

Objeto de Assistente

Campo Type Descrição
id string O identificador, que pode ser referenciado em pontos de extremidade de API.
object string O tipo de objeto, que é sempre assistente.
created_at Número inteiro O carimbo de data/hora do Unix (em segundos), para quando o assistente foi criado.
name cadeia de caracteres ou nulo O nome do assistente. O tamanho máximo é de 256 caracteres.
description cadeia de caracteres ou nulo A descrição do assistente. O tamanho máximo é de 512 caracteres.
model string Nome do nome da implantação de modelo a ser usado.
instructions cadeia de caracteres ou nulo As instruções do sistema que o assistente usa. O tamanho máximo é de 32.768 caracteres.
tools matriz Uma lista de ferramentas habilitada no assistente. Pode haver no máximo 128 ferramentas por assistente. As ferramentas podem ser de tipos code_interpreter ou função. Uma descrição de function pode ter, no máximo, 1.024 caracteres.
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.
temperature número ou nulo O valor padrão é 1. Qual temperatura de amostragem usar, entre 0 e 2. Valores mais altos, como 0,8, tornarão a saída mais aleatória, enquanto valores mais baixos como 0,2 a tornarão mais focada e determinística.
top_p número ou nulo O valor padrão é 1. Uma alternativa à amostragem com temperatura, chamada de amostragem de núcleo, onde o modelo considera os resultados dos tokens com massa de probabilidade top_p. Portanto, 0,1 significa que apenas os tokens que compõem a massa de probabilidade de 10% do topo são considerados. Geralmente, é recomendável alterar este ou a temperatura, mas não ambos.
response_format cadeia de caracteres ou objeto Especifica o formato que o modelo precisa gerar. Compatível com GPT-4 Turbo e todos os modelos GPT-3.5 Turbo a partir do gpt-3.5-turbo-1106. Definir esse parâmetro para { "type": "json_object" } habilita o modo JSON, o que garante que a mensagem gerada pelo modelo seja um JSON válido. É importante ressaltar que, ao usar o modo JSON, você também precisa instruir o modelo a produzir JSON por conta própria usando um sistema ou mensagem de usuário. Sem essa instrução, o modelo pode gerar um fluxo sem fim de espaço em branco até que a geração atinja o limite de token, resultando em uma solicitação de execução longa e aparentemente "paralisada". Além disso, o conteúdo da mensagem pode ser parcialmente cortado se você usa finish_reason="length", o que indica que a geração excedeu max_tokens ou a conversa excedeu o comprimento máximo do contexto.
tool_resources objeto Um conjunto de recursos que são usados pelas ferramentas do assistente. Os recursos são específicos para o tipo de ferramenta. Por exemplo, a ferramenta code_interpreter requer uma lista de IDs de arquivo, enquanto a ferramenta file_search requer uma lista de IDs do repositório de vetores.