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á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_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. |
| 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. |
response_format tipos
string
auto é o valor padrão.
objeto
Valores possíveis type : text, json_object, json_schema.
json_schema
| Nome | Tipo | Description | Predefinido | Obrigatório/Opcional |
|---|---|---|---|---|
description |
string | Uma descrição do formato de resposta, usado pelo modelo para determinar como responder no formato. | Opcional | |
name |
string | O nome do formato de resposta. Deve ser a-z, A-Z, 0-9, ou conter sublinhados e traços, com um comprimento máximo de 64. | Necessário | |
schema |
objeto | O esquema para o formato de resposta, descrito como um objeto de esquema JSON. | Opcional | |
strict |
booleano ou nulo | Se a adesão estrita ao esquema deve ser habilitada ao gerar a saída. Se definido como true, o modelo sempre seguirá o esquema exato definido no schema campo. Somente um subconjunto de esquema JSON é suportado quando strict é true. |
false | Opcional |
tool_resources propriedades
code_interpreter
| Nome | Tipo | Description | Predefinido |
|---|---|---|---|
file_ids |
matriz | Uma lista de IDs de arquivo disponibilizadas para a ferramenta code_interpreter. Pode haver um máximo de 20 arquivos associados à ferramenta. | [] |
file_search
| Nome | Tipo | Description | Obrigatório/Opcional |
|---|---|---|---|
vector_store_ids |
matriz | O armazenamento vetorial anexado a este thread. Pode haver um máximo de 1 armazenamento vetorial anexado ao thread. | Opcional |
vector_stores |
matriz | Um auxiliar para criar um armazenamento de vetores com file_ids e anexá-lo a este thread. Pode haver um máximo de 1 armazenamento vetorial anexado ao thread. | Opcional |
vector_stores
| Nome | Tipo | Description | Obrigatório/Opcional |
|---|---|---|---|
file_ids |
matriz | Uma lista de IDs de arquivo para adicionar ao repositório de vetores. Pode haver um máximo de 10000 arquivos em um armazenamento vetorial. | Opcional |
chunking_strategy |
objeto | A estratégia de fragmentação usada para fragmentar o(s) arquivo(s). Se não estiver definido, usará a estratégia automática. | Opcional |
metadata |
map | Conjunto de 16 pares chave-valor que podem ser anexados a um repositório vetorial. Isso pode ser útil para armazenar informações adicionais sobre o armazenamento vetorial em um formato estruturado. As teclas podem ter no máximo 64 caracteres e os valores podem ter, no máximo, 512 caracteres. | Opcional |
chunking_strategy
| Nome | Tipo | Description | Obrigatório/opcional |
|---|---|---|---|
Auto Chunking Strategy |
objeto | A estratégia padrão. Esta estratégia utiliza atualmente um max_chunk_size_tokens de 800 e chunk_overlap_tokens de 400.
type é sempre auto |
Necessário |
Static Chunking Strategy |
objeto |
type Sempre static |
Necessário |
Estratégia de fragmentação estática
| Nome | Tipo | Description | Obrigatório/Opcional |
|---|---|---|---|
max_chunk_size_tokens |
integer | O número máximo de tokens em cada bloco. O valor predefinido é 800. O valor mínimo é 100 e o valor máximo é 4096. |
Necessário |
chunk_overlap_tokens |
integer | O número de tokens que se sobrepõem entre partes. O valor predefinido é 400. Observe que a sobreposição não deve exceder metade de max_chunk_size_tokens. |
Necessário |
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. |