Referência da API de Assistentes (versão prévia)
Observação
- A pesquisa de arquivos pode ingerir até 10.000 arquivos por assistente, ou seja, 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, ficando pronto para a pesquisa. 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_choiceque 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 32.768 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. |
| file_ids | matriz | Opcional | Usa [] como padrão. Uma lista de IDs de arquivo anexadas a este assistente. Pode haver no máximo 20 arquivos anexados ao assistente. Os arquivos são ordenados pela data de criação em ordem crescente. |
| 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. |
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-05-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"}]
)
Criar arquivo de assistente
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview
Crie um arquivo de assistente anexando um File a um assistant.
Parâmetros de caminho
| Parâmetro | Type | Obrigatória | Descrição |
|---|---|---|---|
assistant_id |
string | Obrigatório | A ID do assistente à qual o arquivo deve ser anexado. |
Corpo da solicitação
| Nome | Digitar | Obrigatória | Descrição |
|---|---|---|---|
| file_id | string | Obrigatório | Uma ID de Arquivo (com purpose="assistants") que o assistente deve usar. Útil para ferramentas como code_interpreter que podem acessar arquivos. |
Retornos
Um objeto de arquivo de assistente.
Exemplo de solicitação de arquivo de criação de assistente
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")
)
assistant_file = client.beta.assistants.files.create(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(assistant_file)
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-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistants = client.beta.assistants.list(
order="desc",
limit="20",
)
print(my_assistants.data)
Listar arquivos do assistente
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview
Retorna uma lista de arquivos de 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. |
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 arquivo do assistente
Exemplo de arquivos de assistente 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")
)
assistant_files = client.beta.assistants.files.list(
assistant_id="asst_abc123"
)
print(assistant_files)
Assistente de recuperação
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)
Recuperar arquivo do assistente
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
Recupera um arquivo do 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. |
| file_id | string | Obrigatório | A ID do arquivo que estamos obtendo |
Retornos
O objeto de arquivo do assistente que corresponde à ID especificada
Exemplo de recuperação de arquivo do assistente
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant_file = client.beta.assistants.files.retrieve(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(assistant_file)
Assistente de modificação
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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. |
file_ids |
matriz | Opcional | Usa [] como padrão. Uma lista de IDs de arquivo anexadas a este assistente. Pode haver no máximo 20 arquivos anexados ao assistente. Os arquivos são ordenados pela data de criação em ordem crescente. Se um arquivo foi anexado anteriormente à lista, mas não aparecer na lista, ele será excluído do assistente. |
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. |
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-05-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
file_ids=["assistant-abc123", "assistant-abc456"],
)
print(my_updated_assistant)
Excluir assistente
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
response = client.beta.assistants.delete("asst_abc123")
print(response)
Excluir arquivo do assistente
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
Exclua um arquivo de 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. |
file_id |
string | Obrigatório | A ID do arquivo a ser excluído |
Retorna
Status de exclusão de arquivo
Exemplo de arquivo de assistente de exclusão
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
deleted_assistant_file = client.beta.assistants.files.delete(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(deleted_assistant_file)
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. |
file_ids |
matriz | Uma lista de IDs de arquivo anexadas a este assistente. Pode haver no máximo 20 arquivos anexados ao assistente. Os arquivos são ordenados pela data de criação em ordem crescente. |
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. |
Objeto de arquivo do 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 assistant.file |
created_at |
Número inteiro | O carimbo de data/hora do Unix (em segundos), para quando o arquivo do assistente foi criado. |
assistant_id |
string | A ID do assistente à qual o arquivo está anexado. |