Partilhar via

Referência da API de Assistentes (Pré-visualização)

  • Artigo

Nota

  • A pesquisa de arquivos pode ingerir até 10.000 arquivos por assistente - 500 vezes mais do que antes. É rápida, suporta consultas paralelas através de pesquisas multi-thread e apresenta reclassificação e reescrita de consultas melhoradas.
    • O arquivo de vetores é um novo objeto da API. Depois de um ficheiro ser adicionado a um arquivo de vetores, é automaticamente analisado, fragmentado e incorporado, ficando pronto para ser pesquisado. Os arquivos de vetores podem ser utilizados entre assistentes e threads, o que simplifica a gestão de ficheiros e a faturação.
  • Adicionamos suporte para o tool_choice parâmetro que pode ser usado para forçar o uso de uma ferramenta específica (como pesquisa de arquivos, 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 (Preview). Orientações 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 do pedido

Nome Type Obrigatório Description
modelo string Obrigatório Nome de implantação do modelo a ser usado.
nome string ou null Opcional O nome do assistente. O comprimento máximo é de 256 caracteres.
descrição string ou null Opcional A descrição do assistente. O comprimento máximo é de 512 caracteres.
instruções string ou null Opcional As instruções do sistema que o assistente usa. O comprimento máximo é de 256.000 caracteres.
ferramentas matriz Opcional O padrão é []. Uma lista de ferramentas ativadas no assistente. Pode haver um máximo de 128 ferramentas por assistente. Atualmente, as ferramentas podem ser do tipo code_interpreter, ou function. Uma function descrição pode ter no máximo 1.024 caracteres.
do IdP 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 teclas podem ter no máximo 64 caracteres e os valores podem ter, no máximo, 512 caracteres.
temperatura número ou nulo Opcional O padrão é 1. Determina a temperatura de amostragem a utilizar, 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 padrão é 1. Uma alternativa à amostragem com temperatura, chamada amostragem de núcleo, onde o modelo considera os resultados dos tokens com top_p massa de probabilidade. Assim, 0,1 significa que apenas os tokens que compõem a massa de probabilidade superior de 10% são considerados. Geralmente recomendamos alterar esta ou a temperatura, mas não ambas.
response_format string ou objeto Opcional Especifica o formato que o modelo deve produzir. Compatível com GPT-4 Turbo e todos os modelos GPT-3.5 Turbo desde gpt-3.5-turbo-1106. Definir esse parâmetro para habilitar o { "type": "json_object" } modo JSON, que garante que a mensagem gerada pelo modelo seja JSON válida. É importante ressaltar que, ao usar o modo JSON, você também deve instruir o modelo a produzir JSON você mesmo usando um sistema ou mensagem de usuário. Sem essa instrução, o modelo pode gerar um fluxo interminável de espaço em branco até que a geração atinja o limite do token, resultando em uma solicitação de longa duração e aparentemente "presa". Além disso, o conteúdo da mensagem pode ser parcialmente cortado se você usar finish_reason="length", o que indica que a geração excedeu max_tokens ou a conversa excedeu o comprimento máximo de 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 code_interpreter ferramenta requer uma lista de IDs de arquivo, enquanto a file_search ferramenta requer uma lista de IDs de armazenamento vetorial.

Devoluções

Um objeto 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 consultas

Parâmetro Type Obrigatório Description
limit integer Opcional Um limite no número de objetos a serem retornados. O limite pode variar entre 1 e 100, e o padrão é 20.
order string Opcional - Padrões para desc Ordem de classificação pelo carimbo de data/hora created_at dos objetos. asc para ordem crescente e desc para ordem decrescente.
after string Opcional Um cursor para uso na paginação. after é um ID de objeto que define o seu lugar na lista. Por exemplo, se você fizer uma solicitação de lista e receber 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 é um ID de objeto que define o seu lugar na lista. Por exemplo, se você fizer uma solicitação de lista e receber 100 objetos, terminando com obj_foo, sua chamada subsequente poderá incluir before=obj_foo para buscar a página anterior da lista.

Devoluções

Uma lista de objetos de assistente

Exemplos 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ório Description
assistant_id string Obrigatório O ID do assistente a ser recuperado.

Devoluções

O objeto 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ório Description
assistant_id string Obrigatório O ID do assistente ao qual o arquivo pertence.

Órgão do Pedido

Parâmetro Type Obrigatório Description
model Opcional O nome de implantação do modelo a ser usado.
name string ou null Opcional O nome do assistente. O comprimento máximo é de 256 caracteres.
description string ou null Opcional A descrição do assistente. O comprimento máximo é de 512 caracteres.
instructions string ou null Opcional As instruções do sistema que o assistente usa. O comprimento máximo é de 32768 caracteres.
tools matriz Opcional O padrão é []. Uma lista de ferramentas ativadas no assistente. Pode haver um máximo de 128 ferramentas por assistente. As ferramentas podem ser do tipo code_interpreter, ou função. Uma function descrição 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 teclas podem ter no máximo 64 caracteres e os valores podem ter, no máximo, 512 caracteres.
temperature número ou nulo Opcional O padrão é 1. Determina a temperatura de amostragem a utilizar, 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 padrão é 1. Uma alternativa à amostragem com temperatura, chamada amostragem de núcleo, onde o modelo considera os resultados dos tokens com top_p massa de probabilidade. Assim, 0,1 significa que apenas os tokens que compõem a massa de probabilidade superior de 10% são considerados. Geralmente recomendamos alterar esta ou a temperatura, mas não ambas.
response_format string ou objeto Opcional Especifica o formato que o modelo deve produzir. Compatível com GPT-4 Turbo e todos os modelos GPT-3.5 Turbo desde gpt-3.5-turbo-1106. Definir esse parâmetro para habilitar o { "type": "json_object" } modo JSON, que garante que a mensagem gerada pelo modelo seja JSON válida. É importante ressaltar que, ao usar o modo JSON, você também deve instruir o modelo a produzir JSON você mesmo usando um sistema ou mensagem de usuário. Sem essa instrução, o modelo pode gerar um fluxo interminável de espaço em branco até que a geração atinja o limite do token, resultando em uma solicitação de longa duração e aparentemente "presa". Além disso, o conteúdo da mensagem pode ser parcialmente cortado se você usar finish_reason="length", o que indica que a geração excedeu max_tokens ou a conversa excedeu o comprimento máximo de 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 code_interpreter ferramenta requer uma lista de IDs de arquivo, enquanto a file_search ferramenta requer uma lista de IDs de armazenamento vetorial.

Devoluções

O objeto 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)

Assistente de exclusão

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ório Description
assistant_id string Obrigatório O ID do assistente ao qual o arquivo pertence.

Devoluções

Estado de eliminaçã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 arquivos como ajuste fino. Ao carregar um arquivo, você precisa especificar um valor apropriado para o parâmetro purpose.

Objeto assistente

Campo Tipo Description
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 integer O carimbo de data/hora Unix (em segundos) para quando o assistente foi criado.
name string ou null O nome do assistente. O comprimento máximo é de 256 caracteres.
description string ou null A descrição do assistente. O comprimento máximo é de 512 caracteres.
model string Nome do nome de implantação do modelo a ser usado.
instructions string ou null As instruções do sistema que o assistente usa. O comprimento máximo é de 32768 caracteres.
tools matriz Uma lista de ferramentas ativadas no assistente. Pode haver um máximo de 128 ferramentas por assistente. As ferramentas podem ser do tipo code_interpreter, ou função. Uma function descrição 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 teclas podem ter no máximo 64 caracteres e os valores podem ter, no máximo, 512 caracteres.
temperature número ou nulo O padrão é 1. Determina a temperatura de amostragem a utilizar, 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 padrão é 1. Uma alternativa à amostragem com temperatura, chamada amostragem de núcleo, onde o modelo considera os resultados dos tokens com top_p massa de probabilidade. Assim, 0,1 significa que apenas os tokens que compõem a massa de probabilidade superior de 10% são considerados. Geralmente recomendamos alterar esta ou a temperatura, mas não ambas.
response_format string ou objeto Especifica o formato que o modelo deve produzir. Compatível com GPT-4 Turbo e todos os modelos GPT-3.5 Turbo desde gpt-3.5-turbo-1106. Definir esse parâmetro para habilitar o { "type": "json_object" } modo JSON, que garante que a mensagem gerada pelo modelo seja JSON válida. É importante ressaltar que, ao usar o modo JSON, você também deve instruir o modelo a produzir JSON você mesmo usando um sistema ou mensagem de usuário. Sem essa instrução, o modelo pode gerar um fluxo interminável de espaço em branco até que a geração atinja o limite do token, resultando em uma solicitação de longa duração e aparentemente "presa". Além disso, o conteúdo da mensagem pode ser parcialmente cortado se você usar finish_reason="length", o que indica que a geração excedeu max_tokens ou a conversa excedeu o comprimento máximo de 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 code_interpreter ferramenta requer uma lista de IDs de arquivo, enquanto a file_search ferramenta requer uma lista de IDs de armazenamento vetorial.