Referência da API de Assistentes (Pré-visualização)
Nota
- A pesquisa de arquivos pode ingerir até 10.000 arquivos por assistente - 500 vezes mais do que antes. É rápido, suporta consultas paralelas através de pesquisas multi-threaded e apresenta reclassificação e reescrita de consultas melhoradas.
- O repositório vetorial é um novo objeto na API. Depois que um arquivo é adicionado a um repositório vetorial, ele é automaticamente analisado, fragmentado e incorporado, pronto para ser pesquisado. Os repositórios vetoriais podem ser usados entre assistentes e threads, simplificando o gerenciamento de arquivos e o faturamento.
- Adicionamos suporte para o
tool_choiceparâ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. |
| file_ids | matriz | Opcional | O padrão é []. Uma lista de IDs de arquivo anexados a este assistente. Pode haver um máximo de 20 arquivos anexados ao assistente. Os ficheiros são ordenados pela sua data de criação por ordem crescente. |
| 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. |
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-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 assistantarquivo .
Parâmetros de caminho
| Parâmetro | Type | Obrigatório | Description |
|---|---|---|---|
assistant_id |
string | Obrigatório | A ID do assistente ao qual o arquivo deve ser anexado. |
Corpo do pedido
| Nome | Type | Obrigatório | Description |
|---|---|---|---|
| file_id | string | Obrigatório | Um ID de arquivo (com purpose="assistants") que o assistente deve usar. Útil para ferramentas como code_interpreter que podem acessar arquivos. |
Devoluções
Um objeto de arquivo assistente.
Exemplo de solicitação de arquivo 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_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 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-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ório | Description |
|---|---|---|---|
| assistant_id | string | Obrigatório | O ID do assistente ao qual o arquivo pertence. |
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 arquivo do assistente
Exemplos 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ó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-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ório | Description |
|---|---|---|---|
| assistant_id | string | Obrigatório | O ID do assistente ao qual o arquivo pertence. |
| file_id | string | Obrigatório | O ID do ficheiro que estamos a receber |
Devoluções
O objeto de arquivo assistente correspondente à ID especificada
Exemplo de arquivo do 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")
)
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ó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. |
file_ids |
matriz | Opcional | O padrão é []. Uma lista de IDs de arquivo anexados a este assistente. Pode haver um máximo de 20 arquivos anexados ao assistente. Os ficheiros são ordenados pela sua data de criação por ordem crescente. Se um arquivo foi anexado anteriormente à lista, mas não aparece 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 teclas podem ter no máximo 64 caracteres e os valores podem ter, no máximo, 512 caracteres. |
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-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)
Assistente de exclusão
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ó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-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ório | Description |
|---|---|---|---|
assistant_id |
string | Obrigatório | O ID do assistente ao qual o arquivo pertence. |
file_id |
string | Obrigatório | A ID do arquivo a ser excluído |
Devoluções
Estado de eliminação de ficheiros
Exemplo de arquivo do 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 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. |
file_ids |
matriz | Uma lista de IDs de arquivo anexados a este assistente. Pode haver um máximo de 20 arquivos anexados ao assistente. Os ficheiros são ordenados pela sua data de criação por 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 teclas podem ter no máximo 64 caracteres e os valores podem ter, no máximo, 512 caracteres. |
Objeto de arquivo do 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 assistant.file |
created_at |
integer | O carimbo de data/hora Unix (em segundos) para quando o arquivo assistente foi criado. |
assistant_id |
string | A ID do assistente à qual o arquivo está anexado. |
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários