Referência de API REST do Serviço OpenAI do Azure

  • Artigo

Este artigo fornece detalhes sobre a API REST de pontos de extremidade de inferência para o OpenAI do Azure.

Autenticação

O OpenAI do Azure fornece dois métodos de autenticação. Você pode usar chaves de API ou o Microsoft Entra ID.

  • Autenticação de chave de API: para esse tipo de autenticação, todas as solicitações de API deverão incluir a Chave de API no cabeçalho HTTP da api-key. O Início Rápido fornece um tutorial de como fazer chamadas com esse tipo de autenticação.

  • Autenticação do Microsoft Entra ID: você pode autenticar uma chamada à API usando um token do Microsoft Entra. Os tokens de autenticação são incluídos em uma solicitação como o cabeçalho Authorization. O token fornecido deverá ser precedido por Bearer, por exemplo Bearer YOUR_AUTH_TOKEN. Você pode ler nosso guia de instruções sobre autenticação com o Microsoft Entra ID.

Controle de versão de API REST

As APIs de serviço são versões que usam o parâmetro de consulta api-version. Todas as versões seguem a estrutura de data AAAA-MM-DD. Por exemplo:

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01

Preenchimentos

Com a operação Conclusões, o modelo gera uma ou mais conclusões previstas com base em um prompt fornecido. O serviço também poderá retornar as probabilidades de tokens alternativos em cada posição.

Criar uma conclusão

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/completions?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
deployment-id string Obrigatório O nome da implantação que você escolheu quando implantou o modelo.
api-version string Obrigatório A versão da API a ser usada para esta operação. Isso segue o formato AAAA-MM-DD.

Versões com suporte

Corpo da solicitação

Parâmetro Type Obrigatório? Padrão Descrição
prompt cadeia de caracteres ou matriz Opcional <\|endoftext\|> O prompt ou prompts para gerar conclusões, codificados como uma cadeia de caracteres, ou uma matriz de cadeia de caracteres. <\|endoftext\|> é o separador de documentos que o modelo reconhece durante o treinamento, portanto, se um prompt não for especificado,o modelo gera a resposta como se estivesse começando um novo documento.
max_tokens Número inteiro Opcional 16 O número máximo de tokens a serem gerados na conclusão. A contagem de tokens da sua solicitação mais max_tokens não pode exceder o tamanho do contexto do modelo. A maioria dos modelos tem um comprimento de contexto de 2048 tokens (exceto para os modelos mais novos, que dão suporte a 4096).
temperature número Opcional 1 Qual temperatura de amostragem usar, entre 0 e 2. Valores mais altos significam que o modelo corre mais riscos. Experimente 0,9 para aplicativos mais criativos e 0 (argmax sampling) para aqueles com uma resposta bem definida. Geralmente, é recomendável alterar este ou top_p, mas não ambos.
top_p número Opcional 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.
logit_bias mapa Opcional nulo Modifica a probabilidade de tokens especificados que aparecerem na conclusão. Aceita um objeto json que mapeia tokens (especificados pela ID de token no tokenizer GPT) para um valor de polarização associado de -100 a 100. É possível usar essa ferramenta tokenizer (que funciona tanto para GPT-2 quanto para GPT-3) para converter texto em IDs de token. Matematicamente, o desvio é adicionado aos logits gerados pelo modelo antes da amostragem. O efeito exato varia por modelo, mas os valores entre -1 e 1 devem diminuir ou aumentar a probabilidade de seleção; valores como -100 ou 100 devem resultar em uma proibição ou seleção exclusiva do token relevante. Como exemplo, é possível passar {"50256": -100} para evitar que o token <|endoftext|> seja gerado.
user string Opcional Um identificador único representando o seu usuário final, que pode ajudar a monitorar e a detectar abusos
n Número inteiro Opcional 1 Quantas conclusões devem ser geradas para cada prompt. Observação: como esse parâmetro gera muitas conclusões, ele poderá consumir rapidamente a sua cota de token. Use com cuidado e garanta configurações razoáveis para max_tokens e de parada.
stream booleano Opcional Falso Se o progresso parcial deverá ser transmitido de volta. Se definidos, os tokens são enviados como eventos enviados apenas por servidor de dados à medida que ficam disponíveis, com o fluxo encerrado por um dado: mensagem [DONE].
logprobs Número inteiro Opcional nulo Inclua as probabilidades de log nos tokens mais prováveis de logprobs, bem como os tokens escolhidos. Por exemplo, se logprobs for 10, a API retornará uma lista dos 10 tokens mais prováveis. A API sempre retornará o logprob do token amostrado, portanto, pode haver até logprobs+1 elementos na resposta. Esse parâmetro não pode ser usado com gpt-35-turbo.
suffix string Opcional nulo O sufixo que vem após a conclusão do texto inserido.
echo booleano Opcional Falso Transmite o prompt de volta além da conclusão. Esse parâmetro não pode ser usado com gpt-35-turbo.
stop cadeia de caracteres ou matriz Opcional nulo Até quatro sequências em que a API deixará de gerar mais tokens. O texto retornado não conterá a sequência de parada. Para GPT-4 Turbo com Vision, há suporte para até duas sequências.
presence_penalty número Opcional 0 Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens com base em se apareceram no texto até o momento, aumentando a probabilidade do modelo apresentar novos tópicos.
frequency_penalty número Opcional 0 Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens com base em sua frequência existente no texto até o momento, diminuindo a probabilidade do modelo repetir a mesma linha na íntegra.
best_of Número inteiro Opcional 1 Gera best_of completações no lado do servidor e retorna o "melhor" (aquele com a menor probabilidade de log por token). Os resultados não podem ser transmitidos. Quando usado com n, best_of controla o número de conclusões de candidatos e n especifica quantos retornar, best_of deve ser maior que n. Observação: como esse parâmetro gera muitas conclusões, ele poderá consumir rapidamente a sua cota de token. Use com cuidado e garanta configurações razoáveis para max_tokens e de parada. Esse parâmetro não pode ser usado com gpt-35-turbo.

Solicitação de exemplo

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01\
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{
  \"prompt\": \"Once upon a time\",
  \"max_tokens\": 5
}"

Exemplo de resposta

{
    "id": "cmpl-4kGh7iXtjW4lc9eGhff6Hp8C7btdQ",
    "object": "text_completion",
    "created": 1646932609,
    "model": "ada",
    "choices": [
        {
            "text": ", a dark line crossed",
            "index": 0,
            "logprobs": null,
            "finish_reason": "length"
        }
    ]
}

No exemplo de resposta, finish_reason é igual a stop. Se finish_reason for igual content_filter a, consulte nosso guia de filtragem de conteúdo para entender por que isso está ocorrendo.

Incorporações

Obtenha uma representação vetorial de uma determinada entrada que pode ser facilmente consumida por modelos de machine learning e outros algoritmos.

Observação

Atualmente, o OpenAI permite um número maior de entradas de matriz com text-embedding-ada-002. Atualmente, o OpenAI do Azure dá suporte a até 16 matrizes de entrada para text-embedding-ada-002 (Version 2). Ambos exigem que o limite máximo de token de entrada por solicitação de API permaneça abaixo de 8191 para esse modelo.

Criar uma incorporação

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/embeddings?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
deployment-id string Obrigatório O nome de sua implantação de modelo. É obrigatório que você implante um modelo antes de poder fazer chamadas.
api-version string Obrigatório A versão da API a ser usada para esta operação. Isso segue o formato AAAA-MM-DD.

Versões com suporte

Corpo da solicitação

Parâmetro Type Obrigatório? Padrão Descrição
input cadeia de caracteres ou matriz Sim N/D Insira o texto para o qual obter incorporações, codificado como uma matriz ou cadeia de caracteres. O número de tokens de entrada varia dependendo do modelo que você está usando. Somente text-embedding-ada-002 (Version 2) dá suporte à entrada de matriz.
user string Não Nulo Um identificador exclusivo que representa o usuário final. Isso ajudará o OpenAI do Azure a monitorar e detectar abusos. Não passe identificadores de PII, em vez disso, use valores pseudoanônimos, como GUIDs.
encoding_format string Não float O formato no qual as inserções devem ser retornadas. Pode ser float ou base64. Assume o padrão de float.

[Adicionado em 2024-03-01-preview].
dimensions Número inteiro Não O número de dimensões que as inserções de saída resultantes devem ter. Só há suporte em modelos text-embedding-3 e posteriores.

[Adicionado em 2024-03-01-preview]

Solicitação de exemplo

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{\"input\": \"The food was delicious and the waiter...\"}"

Exemplo de resposta

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... (1024 floats total for ada)
        0.021276434883475304,
      ],
      "index": 0
    }
  ],
  "model": "text-similarity-babbage:001"
}

Preenchimentos de chat

Crie preenchimentos para mensagens de chat com os modelos GPT-35-Turbo e GPT-4.

Criar preenchimentos de chat

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
deployment-id string Obrigatório O nome de sua implantação de modelo. É obrigatório que você implante um modelo antes de poder fazer chamadas.
api-version string Obrigatório A versão da API a ser usada para esta operação. Isso segue o formato AAAA-MM-DD ou AAAA-MM-DD-preview.

Versões com suporte

Corpo da solicitação

O corpo da solicitação consiste em uma série de mensagens. O modelo vai gerar uma resposta à última mensagem, usando as mensagens anteriores como o contexto.

Parâmetro Type Obrigatório? Padrão Descrição
messages array Sim N/D A série de mensagens associadas a essa solicitação de preenchimento de chat. Ela deve incluir as mensagens anteriores da conversa. Cada mensagem tem uma role e um content.
role string Sim N/D Indica quem está informando a mensagem atual. Pode ser system, user, assistant, tool ou function.
content cadeia de caracteres ou matriz Sim N/D O conteúdo da mensagem. Deve ser uma cadeia de caracteres, a menos que esteja em um cenário habilitado para Visão. Se fizer parte da mensagem user, usando o modelo GPT-4 Turbo com Visão, com a versão mais recente da API, então content deverá ser uma matriz de estruturas, em que cada item representa um texto ou uma imagem:
  • text: o texto de entrada é representado como uma estrutura com as seguintes propriedades:
    • type = "text"
    • text = o texto de entrada
  • images: uma imagem de entrada é representada como uma estrutura com as seguintes propriedades:
    • type = "image_url"
    • image_url = uma estrutura com as seguintes propriedades:
      • url = a URL da imagem
      • (opcional) detail = high, low ou auto
contentPart objeto Não N/D Parte da mensagem multimodal de um usuário. Pode ser tipo de texto ou de imagem. Se for texto, será uma cadeia de texto. Se for imagem, será um objeto contentPartImage.
contentPartImage objeto Não N/D Representa uma imagem carregada pelo usuário. Ele tem uma propriedade url, que é uma URL da imagem ou os dados de imagem codificados em Base64. Também tem uma propriedade detail que pode ser auto, low ou high.
enhancements objeto Não N/D Representa os recursos de aprimoramento da Visão solicitados para o chat. Possui propriedades grounding e ocr, e cada uma delas tem uma propriedade booleana enabled. Use-os para solicitar o serviço OCR e/ou o serviço de detecção/aterramento de objetos [Este parâmetro de visualização não está disponível na API 2024-02-01 GA].
dataSources objeto Não N/D Representa dados de recursos adicionais. Os dados de recursos da Pesquisa Visual Computacional são necessários para o aprimoramento da Visão. Conta com uma propriedade type, que deve ser "AzureComputerVision", e uma propriedade parameters, que tem uma propriedade endpoint e key. Essas cadeias de caracteres devem ser definidas como a URL do ponto de extremidade e a chave de acesso do recurso da Pesquisa Visual Computacional.

Solicitação de exemplo

Chat somente de texto

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},{"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."},{"role": "user", "content": "Do other Azure AI services support this too?"}]}'

Chat com a Visão

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{ "type": "image_url", "image_url": { "url": "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png", "detail": "high" } }]}]}'

Chat aprimorado com a Visão

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"enhancements":{"ocr":{"enabled":true},"grounding":{"enabled":true}},"dataSources":[{"type":"AzureComputerVision","parameters":{"endpoint":" <Computer Vision Resource Endpoint> ","key":"<Computer Vision Resource Key>"}}],"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{"type":"image_url","image_url":"https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"}]}]}'

Exemplo de resposta

{
    "id": "chatcmpl-6v7mkQj980V1yBec6ETrKPRqFjNw9",
    "object": "chat.completion",
    "created": 1679072642,
    "model": "gpt-35-turbo",
    "usage":
    {
        "prompt_tokens": 58,
        "completion_tokens": 68,
        "total_tokens": 126
    },
    "choices":
    [
        {
            "message":
            {
                "role": "assistant",
                "content": "Yes, other Azure AI services also support customer managed keys.
                    Azure AI services offer multiple options for customers to manage keys, such as
                    using Azure Key Vault, customer-managed keys in Azure Key Vault or
                    customer-managed keys through Azure Storage service. This helps customers ensure
                    that their data is secure and access to their services is controlled."
            },
            "finish_reason": "stop",
            "index": 0
        }
    ]
}

Formatação de saída ajustada para facilidade de leitura. A saída real é um único bloco de texto sem quebras de linha.

No exemplo de resposta, finish_reason é igual a stop. Se finish_reason for igual content_filter a, consulte nosso guia de filtragem de conteúdo para entender por que isso está ocorrendo.

Importante

Os parâmetros functions e function_call foram preteridos com a versão 2023-12-01-preview da API. A substituição para functions é o parâmetro tools. A substituição para function_call é o parâmetro tool_choice. A chamada de funções paralelas, introduzida como parte do 2023-12-01-preview, só tem suporte para o gpt-35-turbo (1106) e o gpt-4 (1106-preview), também conhecido como Versão prévia do GPT-4 Turbo.

Parâmetro Type Obrigatório? Padrão Descrição
messages array Obrigatório A coleção de mensagens de contexto associadas a esta solicitação de preenchimentos de chat. O uso típico começa com uma mensagem de chat para a função Sistema que fornece instruções para o comportamento do assistente, seguida por mensagens alternadas entre as funções Usuário e Assistente.
temperature number Opcional 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. Geralmente recomendamos alterar isso ou top_p, mas não as duas coisas.
n Número inteiro Opcional 1 Quantas opções de preenchimento de chat serão geradas para cada mensagem de entrada.
stream booleano Opcional false Se forem definidos, os deltas de mensagens parciais serão enviados, como no ChatGPT. Se forem definidos, os tokens serão enviados como eventos somente de dados enviados pelo servidor à medida que estiverem disponíveis, com a transmissão sendo encerrada por uma mensagem data: [DONE].
stop cadeia de caracteres ou matriz Opcional nulo Até quatro sequências nas quais a API irá parar de gerar tokens.
max_tokens Número inteiro Opcional inf O número máximo de tokens permitidos para a resposta gerada. Por padrão, o número de tokens que o modelo pode retornar será (4096 — tokens de prompt).
presence_penalty número Opcional 0 Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens com base em se apareceram no texto até o momento, aumentando a probabilidade do modelo apresentar novos tópicos.
frequency_penalty número Opcional 0 Número entre -2.0 e 2.0. Valores positivos penalizam novos tokens com base em sua frequência existente no texto até o momento, diminuindo a probabilidade do modelo repetir a mesma linha na íntegra.
logit_bias objeto Opcional nulo Modifica a probabilidade de tokens especificados que aparecerem na conclusão. Aceita um objeto json que mapeia tokens (especificados por sua ID de token no tokenizador) para um respectivo valor de viés de -100 a 100. Matematicamente, o desvio é adicionado aos logits gerados pelo modelo antes da amostragem. O efeito exato varia por modelo, mas os valores entre -1 e 1 devem diminuir ou aumentar a probabilidade de seleção; valores como -100 ou 100 devem resultar em uma proibição ou seleção exclusiva do token relevante.
user string Opcional Um identificador único representando o seu usuário final, que pode ajudar o OpenAI do Azure a monitorar e detectar abusos.
function_call Opcional [Deprecated in 2023-12-01-preview replacement parameter is tools_choice]Controla como o modelo responde às chamadas de função. "none" significa que o modelo não chama uma função e responde ao usuário final. auto significa que o modelo pode escolher entre um usuário final ou chamar uma função. Especificar uma determinada função por meio de {"name": "my_function"} força o modelo a chamar essa função. “none” é o padrão quando nenhuma função está presente. auto é o padrão, caso haja funções presentes. Esse parâmetro requer a versão da API 2023-07-01-preview
functions FunctionDefinition[] Opcional [Deprecated in 2023-12-01-preview replacement paremeter is tools]Uma lista de funções para as quais o modelo pode gerar entradas JSON. Esse parâmetro requer a versão da API 2023-07-01-preview
tools cadeia de caracteres (o tipo da ferramenta. Apenas function tem suporte.) Opcional Uma lista de ferramentas que o modelo pode chamar. No momento, há suporte apenas para funções como uma ferramenta. Use isso para fornecer uma lista de funções para as quais o modelo pode gerar entradas JSON. Esse parâmetro requer a versão da API 2023-12-01-preview
tool_choice cadeia de caracteres ou objeto Opcional "none" é o padrão quando não há funções presentes. auto é o padrão, caso haja funções presentes. Controla qual função (se houver) é chamada pelo modelo. None significa que o modelo não chamará uma função e, em vez disso, vai gerar uma mensagem. auto significa que o modelo pode escolher entre gerar uma mensagem ou chamar uma função. Especificar uma determinada função por meio de {"type: "function", "function": {"name": "my_function"}} força o modelo a chamar essa função. Esse parâmetro exige a versão da API 2023-12-01-preview ou posterior.

ChatMessage

Uma única mensagem atribuída por função dentro de uma interação de preenchimento de chat.

Nome Tipo Descrição
conteúdo string O texto associado a este conteúdo de mensagem.
function_call FunctionCall O nome e os argumentos de uma função que deve ser chamada, conforme gerado pelo modelo.
name string O name do autor desta mensagem. name será necessário se a função for function e deve ser o nome da função cuja resposta está no content. Pode conter a-z, A-Z, 0-9 e sublinhados, com um comprimento máximo de 64 caracteres.
função ChatRole A função associada a este conteúdo de mensagem

ChatRole

Uma descrição da finalidade pretendida de uma mensagem dentro de uma interação de preenchimentos de chat.

Nome Tipo Descrição
assistente string A função que fornece respostas à entrada solicitada pelo usuário e instruída pelo sistema.
function string A função que fornece resultados de função para preenchimentos de chat.
sistema string A função que instrui ou define o comportamento do assistente.
usuário string A função que fornece entrada para preenchimentos de chat.

Função

Isso é usado com o parâmetro tools que foi adicionado na versão 2023-12-01-preview da API.

Nome Tipo Descrição
descrição string Uma descrição do que a função faz, usada pelo modelo para escolher quando e como chamar a função
name string O nome da função que será chamada. Deve ser a-z, A-Z, 0-9 ou conter sublinhados e traços, com um comprimento máximo de 64
parâmetros objeto Os parâmetros que as funções aceitam, descritos como um objeto de Esquema JSON. Confira a referência de Esquema JSON para obter documentação sobre o formato."

FunctionCall-Deprecated

O nome e os argumentos de uma função que deve ser chamada, conforme gerado pelo modelo. Isso requer a versão da API 2023-07-01-preview

Nome Tipo Descrição
argumentos string Os argumentos com os quais chamar a função, conforme gerado pelo modelo no formato JSON. O modelo nem sempre gera JSON válido e pode fabricar parâmetros não definidos pelo esquema de função. Valide os argumentos em seu código antes de chamar sua função.
name string O nome da função a ser chamada.

FunctionDefinition-Deprecated

A definição de uma função especificada pelo chamador que as conclusões do chat podem invocar em resposta à entrada do usuário correspondente. Isso requer a versão da API 2023-07-01-preview

Nome Tipo Descrição
descrição string Uma descrição do que a função faz. O modelo usa essa descrição ao selecionar a função e interpretar seus parâmetros.
name string O nome da função que será chamada.
parameters Os parâmetros que as funções aceitam, descritos como um objeto de Esquema JSON.

Extensões de preenchimento

Extensões para preenchimento de chats, por exemplo, o Azure OpenAI On Your Data.

Importante

As informações a seguir são para a versão 2023-12-01-preview da API. Essa não é a versão atual da API. Para encontrar a documentação de referência mais recente, veja Referência do Azure OpenAI em seus dados.

Usar extensões de preenchimento de chats

POST {your-resource-name}/openai/deployments/{deployment-id}/extensions/chat/completions?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
deployment-id string Obrigatório O nome de sua implantação de modelo. É obrigatório que você implante um modelo antes de poder fazer chamadas.
api-version string Obrigatório A versão da API a ser usada para esta operação. Isso segue o formato AAAA-MM-DD.

Versões com suporte

Solicitação de exemplo

Você pode fazer solicitações usando a Pesquisa de IA do Azure, o Azure Cosmos DB for MongoDB vCore, o Pinecone e a Elasticsearch. Para saber mais, confira Azure OpenAI On Your Data.

curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-06-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
    "temperature": 0,
    "max_tokens": 1000,
    "top_p": 1.0,
    "dataSources": [
        {
            "type": "AzureCognitiveSearch",
            "parameters": {
                "endpoint": "YOUR_AZURE_COGNITIVE_SEARCH_ENDPOINT",
                "key": "YOUR_AZURE_COGNITIVE_SEARCH_KEY",
                "indexName": "YOUR_AZURE_COGNITIVE_SEARCH_INDEX_NAME"
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the differences between Azure Machine Learning and Azure AI services?"
        }
    ]
}
'
Azure Cosmos DB para MongoDB vCore
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-06-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
    "temperature": 0,
    "top_p": 1.0,
    "max_tokens": 800,
    "stream": false,
    "messages": [
        {
            "role": "user",
            "content": "What is the company insurance plan?"
        }
    ],
    "dataSources": [
        {
            "type": "AzureCosmosDB",
            "parameters": {
                "authentication": {
                    "type": "ConnectionString",
                    "connectionString": "mongodb+srv://onyourdatatest:{password}$@{cluster-name}.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000"
                },
                "databaseName": "vectordb",
                "containerName": "azuredocs",
                "indexName": "azuredocindex",
                "embeddingDependency": {
                    "type": "DeploymentName",
                    "deploymentName": "{embedding deployment name}"
                },
                "fieldsMapping": {
                    "vectorFields": [
                        "contentvector"
                    ]
                }
            }
        }
    ]
}
'
Elasticsearch
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
{
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful assistant that talks like a pirate"
    },
    {
      "role": "user",
      "content": "can you tell me how to care for a parrot?"
    }
  ],
  "dataSources": [
    {
      "type": "Elasticsearch",
      "parameters": {
        "endpoint": "{search endpoint}",
        "indexName": "{index name}",
        "authentication": {
          "type": "KeyAndKeyId",
          "key": "{key}",
          "keyId": "{key id}"
        }
      }
    }
  ]
}
Azure Machine Learning
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful assistant that talks like a pirate"
    },
    {
      "role": "user",
      "content": "can you tell me how to care for a parrot?"
    }
  ],
  "dataSources": [
    {
      "type": "AzureMLIndex",
      "parameters": {
        "projectResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.MachineLearningServices/workspaces/{workspace-id}",
        "name": "my-project",
        "version": "5"
      }
    }
  ]
}
'
Pinecone
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful assistant that talks like a pirate"
    },
    {
      "role": "user",
      "content": "can you tell me how to care for a parrot?"
    }
  ],
  "dataSources": [
    {
      "type": "Pinecone",
      "parameters": {
        "authentication": {
          "type": "APIKey",
          "apiKey": "{api key}"
        },
        "environment": "{environment name}",
        "indexName": "{index name}",
        "embeddingDependency": {
          "type": "DeploymentName",
          "deploymentName": "{embedding deployment name}"
        },
        "fieldsMapping": {
          "titleField": "title",
          "urlField": "url",
          "filepathField": "filepath",
          "contentFields": [
            "content"
          ],
          "contentFieldsSeparator": "\n"
        }
      }
    }
  ]
}
'

Exemplo de resposta

{
    "id": "12345678-1a2b-3c4e5f-a123-12345678abcd",
    "model": "",
    "created": 1684304924,
    "object": "chat.completion",
    "choices": [
        {
            "index": 0,
            "messages": [
                {
                    "role": "tool",
                    "content": "{\"citations\": [{\"content\": \"\\nAzure AI services are cloud-based artificial intelligence (AI) services...\", \"id\": null, \"title\": \"What is Azure AI services\", \"filepath\": null, \"url\": null, \"metadata\": {\"chunking\": \"orignal document size=250. Scores=0.4314117431640625 and 1.72564697265625.Org Highlight count=4.\"}, \"chunk_id\": \"0\"}], \"intent\": \"[\\\"Learn about Azure AI services.\\\"]\"}",
                    "end_turn": false
                },
                {
                    "role": "assistant",
                    "content": " \nAzure AI services are cloud-based artificial intelligence (AI) services that help developers build cognitive intelligence into applications without having direct AI or data science skills or knowledge. [doc1]. Azure Machine Learning is a cloud service for accelerating and managing the machine learning project lifecycle. [doc1].",
                    "end_turn": true
                }
            ]
        }
    ]
}
Parâmetros Type Obrigatório? Padrão Descrição
messages array Obrigatório nulo As mensagens para as quais gerar preenchimentos de chat, no formato do chat.
dataSources array Obrigatório As fontes de dados a serem usadas pela funcionalidade Azure OpenAI On Your Data.
temperature número Opcional 0 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. Geralmente recomendamos alterar isso ou top_p, mas não as duas coisas.
top_p número Opcional 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.
stream booleano Opcional false Se definido, deltas de mensagem parciais são enviados, como no ChatGPT. Os tokens são enviados como eventos enviados pelo servidor somente dados à medida que ficam disponíveis, com o fluxo encerrado por uma mensagem "messages": [{"delta": {"content": "[DONE]"}, "index": 2, "end_turn": true}]
stop cadeia de caracteres ou matriz Opcional nulo Até duas sequências em que a API deixará de gerar tokens adicionais.
max_tokens Número inteiro Opcional 1000 O número máximo de tokens permitidos para a resposta gerada. Por padrão, o número de tokens que o modelo pode retornar é 4096 - prompt_tokens.

Os parâmetros a seguir podem ser usados dentro do campo parameters dentro das dataSources.

Parâmetros Type Obrigatório? Padrão Descrição
type string Obrigatório nulo A fonte de dados a ser usada pela funcionalidade Azure OpenAI On Your Data. Para o IA do Azure Search, o valor é AzureCognitiveSearch. Para o Azure Cosmos DB for MongoDB vCore, o valor é AzureCosmosDB. Para o Elasticsearch, o valor é Elasticsearch. Para o Azure Machine Learning, o valor é AzureMLIndex. Para o Pinecone, o valor é Pinecone.
indexName string Obrigatório nulo O índice de pesquisa a ser usado.
inScope boolean Opcional true Se definido, esse valor limitará as respostas específicas ao conteúdo dos dados de aterramento.
topNDocuments número Opcional 5 Especifica o número de documentos de maior pontuação do índice de dados usados para gerar respostas. Talvez você queira aumentar o valor quando tiver documentos curtos ou quiser acrescentar mais contexto. Este é o parâmetro de documentos recuperados no Estúdio do Azure OpenAI.
semanticConfiguration string Opcional nulo A configuração da pesquisa semântica. Necessário somente quando queryType é definido como semantic ou vectorSemanticHybrid.
roleInformation string Opcional nulo Fornece instruções ao modelo sobre como ele deve se comportar e o contexto que deve referenciar ao gerar uma resposta. Corresponde à "Mensagem do Sistema" no Azure OpenAI Studio. Veja Usando seus dados para obter mais informações. Há um limite de 100 tokens, que conta para o limite geral do token.
filter string Opcional nulo O padrão de filtro usado para restringir o acesso a documentos confidenciais
embeddingEndpoint string Opcional nulo A URL do ponto de extremidade para uma implantação de modelo de inserção do Ada, geralmente do formato https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2023-05-15. Use com o parâmetro embeddingKey para busca em vetores fora de redes privadas e pontos de extremidade privados.
embeddingKey string Opcional nulo A chave de API para uma implantação de modelo de incorporação Ada. Use com embeddingEndpoint para busca em vetores fora de redes privadas e pontos de extremidade privados.
embeddingDeploymentName string Opcional nulo O nome de implantação do modelo de inserção do Ada no mesmo recurso do Azure OpenAI. Usado em vez de embeddingEndpoint e embeddingKey para busca em vetores. Só deve ser usado quando os parâmetros embeddingEndpoint e embeddingKey forem definidos. Quando esse parâmetro é fornecido, o Azure OpenAI On Your Data usa uma chamada interna para avaliar o modelo de inserção do Ada, em vez de chamar o ponto de extremidade do Azure OpenAI. Isso permite que você use a busca em vetores em redes privadas e pontos de extremidade privados. A cobrança permanece a mesma se esse parâmetro for definido ou não. Disponível em regiões em que os modelos de inserção estão disponíveis a partir de versões 2023-06-01-preview de API e posteriores.
strictness number Opcional 3 Define o limite para categorizar os documentos como relevantes para suas consultas. Aumentar o valor significa um limite mais alto de relevância e elimina os documentos menos relevantes para as respostas. Ao definir um valor muito alto, é possível que o modelo não consiga gerar respostas devido à limitação de documentos disponíveis.

Parâmetros da Pesquisa de IA do Azure

Os seguintes parâmetros são utilizados na Pesquisa de IA do Azure.

Parâmetros Type Obrigatório? Padrão Descrição
endpoint string Obrigatório nulo Somente o IA do Azure Search. O ponto de extremidade da fonte de dados.
key string Obrigatório nulo Somente o IA do Azure Search. Uma das chaves de administrador do IA do Azure Search para seu serviço.
queryType string Opcional simple Indica qual opção de consulta é usada para a Pesquisa de IA do Azure. Tipos disponíveis: simple, semantic, vector, vectorSimpleHybrid, vectorSemanticHybrid.
fieldsMapping dicionário Opcional para o IA do Azure Search. nulo define quais campos que você deseja mapear ao adicionar sua fonte de dados.

Os parâmetros a seguir são utilizados dentro do campo authentication, o que permite que você use o OpenAI do Azure sem acesso à rede pública.

Parâmetros Type Obrigatório? Padrão Descrição
type string Obrigatório nulo O tipo de autenticação.
managedIdentityResourceId string Obrigatório nulo A ID do recurso da identidade gerenciada atribuída pelo usuário a ser usada para autenticação. 
"authentication": {
  "type": "UserAssignedManagedIdentity",
  "managedIdentityResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{resource-name}"
},

Os parâmetros a seguir são usados dentro do campofieldsMapping.

Parâmetros Type Obrigatório? Padrão Descrição
titleField string Opcional nulo O campo em seu índice que contém o título original de cada documento.
urlField string Opcional nulo O campo em seu índice que contém a URL original de cada documento.
filepathField string Opcional nulo O campo em seu índice que contém o nome de arquivo original de cada documento.
contentFields dicionário Opcional nulo Os campos em seu índice que contêm o conteúdo de texto principal de cada documento.
contentFieldsSeparator string Opcional nulo O separador para os campos de conteúdo. Use \n por padrão. 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n"
}

Os parâmetros a seguir são usados dentro do parâmetro opcional embeddingDependency, que contém detalhes de uma fonte de vetorização baseada em um nome de implantação de modelo de inserções internas no mesmo recurso do OpenAI do Azure.

Parâmetros Type Obrigatório? Padrão Descrição
deploymentName string Opcional nulo O tipo de fonte de vetorização a ser usado.
type string Opcional nulo O nome da implantação do modelo de inserção, localizado no mesmo recurso do OpenAI do Azure. Isso permite que você use a busca em vetores sem uma chave de API do OpenAI do Azure e sem acesso à rede pública do OpenAI do Azure. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Parâmetros do Azure Cosmos DB para MongoDB vCore

Os seguintes parâmetros são utilizados para o Azure Cosmos DB for MongoDB vCore.

Parâmetros Type Obrigatório? Padrão Descrição
type (encontrado dentro de authentication) string Obrigatório nulo Somente o Azure Cosmos DB for MongoDB vCore. A autenticação a ser usada para. Azure Cosmos Mongo vCore, o valor é ConnectionString
connectionString string Obrigatório nulo Somente o Azure Cosmos DB for MongoDB vCore. A cadeia de conexão a ser usada para autenticar a Conta vCore do Azure Cosmos Mongo.
databaseName string Obrigatório nulo Somente o Azure Cosmos DB for MongoDB vCore. O nome do banco de dados vCore do Azure Cosmos Mongo.
containerName string Obrigatório nulo Somente o Azure Cosmos DB for MongoDB vCore. O nome do contêiner do Azure Cosmos Mongo vCore no banco de dados.
type (encontrado dentro deembeddingDependencyType) string Obrigatório nulo Indica a dependência do modelo de inserção.
deploymentName (encontrado dentro deembeddingDependencyType) string Obrigatório nulo O nome da implantação do modelo de inserção.
fieldsMapping dicionário Necessário para o Azure Cosmos DB for MongoDB vCore. nulo Mapeamento de coluna de dados de índice. Quando você usa o Azure Cosmos DB for MongoDB vCore, o valor vectorFields é obrigatório, o que indica os campos que armazenam vetores.

Os parâmetros a seguir são usados dentro do parâmetro opcional embeddingDependency, que contém detalhes de uma fonte de vetorização baseada em um nome de implantação de modelo de inserções internas no mesmo recurso do OpenAI do Azure.

Parâmetros Type Obrigatório? Padrão Descrição
deploymentName string Opcional nulo O tipo de fonte de vetorização a ser usado.
type string Opcional nulo O nome da implantação do modelo de inserção, localizado no mesmo recurso do OpenAI do Azure. Isso permite que você use a busca em vetores sem uma chave de API do OpenAI do Azure e sem acesso à rede pública do OpenAI do Azure. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Parâmetros do Elasticsearch

Os seguintes parâmetros são utilizados para o Elasticsearch.

Parâmetros Type Obrigatório? Padrão Descrição
endpoint string Obrigatório nulo O ponto de extremidade para conexão com o Elasticsearch.
indexName string Obrigatório nulo O nome do índice do Elasticsearch.
type (encontrado dentro deauthentication) string Obrigatório nulo A autenticação a ser utilizada. Para o Elasticsearch, o valor é KeyAndKeyId.
key (encontrado dentro deauthentication) string Obrigatório nulo A chave usada para se conectar ao Elasticsearch.
keyId (encontrado dentro deauthentication) string Obrigatório nulo A ID da chave a ser usada. Para o Elasticsearch.

Os parâmetros a seguir são usados dentro do campofieldsMapping.

Parâmetros Type Obrigatório? Padrão Descrição
titleField string Opcional nulo O campo em seu índice que contém o título original de cada documento.
urlField string Opcional nulo O campo em seu índice que contém a URL original de cada documento.
filepathField string Opcional nulo O campo em seu índice que contém o nome de arquivo original de cada documento.
contentFields dicionário Opcional nulo Os campos em seu índice que contêm o conteúdo de texto principal de cada documento.
contentFieldsSeparator string Opcional nulo O separador para os campos de conteúdo. Use \n por padrão.
vectorFields dicionário Opcional nulo Os nomes dos campos que representam dados vetoriais 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n",
  "vectorFields": [
    "myVectorField"
  ]
}

Os parâmetros a seguir são usados dentro do parâmetro opcional embeddingDependency, que contém detalhes de uma fonte de vetorização baseada em um nome de implantação de modelo de inserções internas no mesmo recurso do OpenAI do Azure.

Parâmetros Type Obrigatório? Padrão Descrição
deploymentName string Opcional nulo O tipo de fonte de vetorização a ser usado.
type string Opcional nulo O nome da implantação do modelo de inserção, localizado no mesmo recurso do OpenAI do Azure. Isso permite que você use a busca em vetores sem uma chave de API do OpenAI do Azure e sem acesso à rede pública do OpenAI do Azure. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Parâmetros do Microsoft Azure Machine Learning

Os seguintes parâmetros são utilizados no Azure Machine Learning.

Parâmetros Type Obrigatório? Padrão Descrição
projectResourceId string Obrigatório nulo A ID do recurso do projeto.
name string Obrigatório nulo O nome do projeto do Microsoft Azure Machine Learning.
version (encontrado dentro deauthentication) string Obrigatório nulo A versão do índice de vetores do Azure Machine Learning.

Os parâmetros a seguir são usados dentro do parâmetro opcional embeddingDependency, que contém detalhes de uma fonte de vetorização baseada em um nome de implantação de modelo de inserções internas no mesmo recurso do OpenAI do Azure.

Parâmetros Type Obrigatório? Padrão Descrição
deploymentName string Opcional nulo O tipo de fonte de vetorização a ser usado.
type string Opcional nulo O nome da implantação do modelo de inserção, localizado no mesmo recurso do OpenAI do Azure. Isso permite que você use a busca em vetores sem uma chave de API do OpenAI do Azure e sem acesso à rede pública do OpenAI do Azure. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Parâmetros do Pinecone

Os seguintes parâmetros são utilizados no Pinecone.

Parâmetros Type Obrigatório? Padrão Descrição
type (encontrado dentro de authentication) string Obrigatório nulo A autenticação a ser utilizada. Para o Pinecone, o valor é APIKey.
apiKey (encontrado dentro deauthentication) string Obrigatório nulo A chave de API do Pinecone.
environment string Obrigatório nulo O nome do ambiente do Pinecone.
indexName string Obrigatório nulo O nome do índice do Pinecone.
embeddingDependency string Obrigatório nulo A dependência de inserção para a busca em vetores.
type (encontrado dentro deembeddingDependency) string Obrigatório nulo O tipo de dependência. Para o Pinecone, o valor é DeploymentName.
deploymentName (encontrado dentro deembeddingDependency) string Obrigatório nulo O nome da implantação.
titleField (encontrado dentro defieldsMapping) string Obrigatório nulo O nome do campo de índice a ser utilizado como título.
urlField (encontrado dentro defieldsMapping) string Obrigatório nulo O nome do campo de índice a ser utilizado como URL.
filepathField (encontrado dentro defieldsMapping) string Obrigatório nulo O nome do campo de índice a ser utilizado como um caminho de arquivo.
contentFields (encontrado dentro defieldsMapping) string Obrigatório nulo O nome dos campos de índice que devem ser tratados como conteúdo.
vectorFields dicionário Opcional nulo Os nomes dos campos que representam dados vetoriais
contentFieldsSeparator (encontrado dentro defieldsMapping) string Obrigatório nulo O separador para seus campos de conteúdo. Use \n por padrão.

Os parâmetros a seguir são usados dentro do parâmetro opcional embeddingDependency, que contém detalhes de uma fonte de vetorização baseada em um nome de implantação de modelo de inserções internas no mesmo recurso do OpenAI do Azure.

Parâmetros Type Obrigatório? Padrão Descrição
deploymentName string Opcional nulo O tipo de fonte de vetorização a ser usado.
type string Opcional nulo O nome da implantação do modelo de inserção, localizado no mesmo recurso do OpenAI do Azure. Isso permite que você use a busca em vetores sem uma chave de API do OpenAI do Azure e sem acesso à rede pública do OpenAI do Azure. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Iniciar um trabalho de ingestão (em versão prévia)

Dica

A JOB_NAME escolha será usada como o nome do índice. Lembre-se das restrições para o nome do índice.

curl -i -X PUT https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/JOB_NAME?api-version=2023-10-01-preview \ 
-H "Content-Type: application/json" \ 
-H "api-key: YOUR_API_KEY" \ 
-H "searchServiceEndpoint: https://YOUR_AZURE_COGNITIVE_SEARCH_NAME.search.windows.net" \ 
-H "searchServiceAdminKey: YOUR_SEARCH_SERVICE_ADMIN_KEY" \ 
-H  "storageConnectionString: YOUR_STORAGE_CONNECTION_STRING" \ 
-H "storageContainer: YOUR_INPUT_CONTAINER" \ 
-d '{ "dataRefreshIntervalInMinutes": 10 }'

Exemplo de resposta

{ 
    "id": "test-1", 
    "dataRefreshIntervalInMinutes": 10, 
    "completionAction": "cleanUpAssets", 
    "status": "running", 
    "warnings": [], 
    "progress": { 
        "stageProgress": [ 
            { 
                "name": "Preprocessing", 
                "totalItems": 100, 
                "processedItems": 100 
            }, 
            { 
                "name": "Indexing", 
                "totalItems": 350, 
                "processedItems": 40 
            } 
        ] 
    } 
}

Parâmetros do Cabeçalho

Parâmetros Type Obrigatório? Padrão Descrição
searchServiceEndpoint string Obrigatório nulo O ponto de extremidade do recurso de pesquisa no qual os dados serão ingeridos.
searchServiceAdminKey string Opcional nulo Se fornecida, a chave será usada para autenticar com o searchServiceEndpoint. Se não for fornecido, a identidade atribuída pelo sistema do recurso Azure OpenAI será usada. Nesse caso, a identidade atribuída pelo sistema deve ter a atribuição de função "Colaborador do Serviço de Pesquisa" no recurso de pesquisa.
storageConnectionString string Obrigatório nulo A cadeia de conexão da conta de armazenamento em que os dados de entrada estão localizados. Uma chave de conta deve ser fornecida na cadeia de conexão. Deve ser algo parecido com DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>
storageContainer string Obrigatório nulo O nome do contêiner em que os dados de entrada estão localizados.
embeddingEndpoint string Opcional nulo Não é necessário se você usar a pesquisa semântica ou apenas de palavra-chave. É necessário se você usar a pesquisa vetor, híbrida ou híbrida + semântica
embeddingKey string Opcional nulo A chave do ponto de extremidade de inserção. Isso será necessário se o ponto de extremidade de inserção não estiver vazio.
url string Opcional nulo Se a URL não for nula, a URL fornecida será rastreada para o contêiner de armazenamento fornecido e ingerida adequadamente.

Parâmetros do Corpo

Parâmetros Type Obrigatório? Padrão Descrição
dataRefreshIntervalInMinutes string Obrigatório 0 O intervalo de atualização de dados em minutos. Se você quiser executar um único trabalho de ingestão sem um agendamento, defina esse parâmetro como 0.
completionAction string Opcional cleanUpAssets O que deve acontecer com os ativos criados durante o processo de ingestão após a conclusão do trabalho. Os valores válidos são cleanUpAssets ou keepAllAssets. keepAllAssets deixa todos os ativos intermediários para usuários interessados em examinar os resultados intermediários, o que pode ser útil para depuração de ativos. cleanUpAssets remove os ativos após a conclusão do trabalho.
chunkSize INT Opcional 1024 Esse número define o número máximo de tokens em cada parte produzida pelo fluxo de ingestão.

Listar trabalhos de ingestão (em versão prévia)

curl -i -X GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs?api-version=2023-10-01-preview \ 
-H "api-key: YOUR_API_KEY"

Exemplo de resposta

{ 
    "value": [ 
        { 
            "id": "test-1", 
            "dataRefreshIntervalInMinutes": 10, 
            "completionAction": "cleanUpAssets", 
            "status": "succeeded", 
            "warnings": [] 
        }, 
        { 
            "id": "test-2", 
            "dataRefreshIntervalInMinutes": 10, 
            "completionAction": "cleanUpAssets", 
            "status": "failed", 
            "error": { 
                "code": "BadRequest", 
                "message": "Could not execute skill because the Web Api request failed." 
            }, 
            "warnings": [] 
        } 
    ] 
}

Obter o status de um trabalho de ingestão (em versão prévia)

curl -i -X GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/YOUR_JOB_NAME?api-version=2023-10-01-preview \ 
-H "api-key: YOUR_API_KEY"

Corpo da resposta de exemplo

{ 
    "id": "test-1", 
    "dataRefreshIntervalInMinutes": 10, 
    "completionAction": "cleanUpAssets", 
    "status": "succeeded", 
    "warnings": [] 
}

Geração de imagem

Solicitar uma imagem gerada (DALL-E 3)

Gerar e recuperar um lote de imagens a partir de uma legenda.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
deployment-id string Obrigatório O nome da implantação de modelo DALL-E 3, como MyDalle3. Será necessário primeiro implantar um modelo DALL-E 3 antes de fazer as chamadas.
api-version string Obrigatório A versão da API a ser usada para esta operação. Isso segue o formato AAAA-MM-DD.

Versões com suporte

Corpo da solicitação

Parâmetro Type Obrigatório? Padrão Descrição
prompt string Obrigatório Uma descrição de texto das imagens desejadas. O tamanho máximo é de 4.000 caracteres.
n Número inteiro Opcional 1 O número de imagens a serem geradas. Somente n=1 tem suporte para DALL-E 3.
size string Opcional 1024x1024 O tamanho das imagens geradas. Pode ser 1792x1024, 1024x1024 ou 1024x1792.
quality string Opcional standard A qualidade das imagens geradas. Deve ser hd ou standard.
response_format string Opcional url O formato no qual as imagens geradas são retornadas deve ser url (uma URL apontando para a imagem) ou b64_json (o código de byte base 64 no formato JSON).
style string Opcional vivid O estilo das imagens geradas. Deve ser natural ou vivid (para imagens hiper-realistas/dramáticas).
user string Opcional Um identificador exclusivo que representa o usuário final, o qual pode ajudar a monitorar e detectar abusos.

Solicitação de exemplo

curl -X POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "An avocado chair",
    "size": "1024x1024",
    "n": 1,
    "quality": "hd", 
    "style": "vivid"
  }'

Exemplo de resposta

A operação retorna um código de status 202 e um objeto JSON de GenerateImagesResponse que contém a ID e o status da operação.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "url": "url to the image", 
            "revised_prompt": "the actual prompt that was used" 
        }, 
        { 
            "url": "url to the image" 
        },
        ...
    ]
}

Solicite uma imagem gerada (versão prévia do DALL-E 2)

Gerar um lote de imagens a partir de uma legenda.

POST https://{your-resource-name}.openai.azure.com/openai/images/generations:submit?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
api-version string Obrigatório A versão da API a ser usada para esta operação. Isso segue o formato AAAA-MM-DD.

Versões com suporte

Corpo da solicitação

Parâmetro Type Obrigatório? Padrão Descrição
prompt string Obrigatório Uma descrição de texto das imagens desejadas. O comprimento máximo é de 1.000 caracteres.
n Número inteiro Opcional 1 O número de imagens a serem geradas. Precisa estar entre 1 e 5.
size string Opcional 1\.024 x 1.024 O tamanho das imagens geradas. Pode ser 256x256, 512x512 ou 1024x1024.

Solicitação de exemplo

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/images/generations:submit?api-version=2023-06-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
"prompt": "An avocado chair",
"size": "512x512",
"n": 3
}'

Exemplo de resposta

A operação retorna um código de status 202 e um objeto JSON de GenerateImagesResponse que contém a ID e o status da operação.

{
  "id": "f508bcf2-e651-4b4b-85a7-58ad77981ffa",
  "status": "notRunning"
}

Obtenha um resultado de imagem gerado (versão prévia do DALL-E 2)

Use essa API para recuperar os resultados de uma operação de geração de imagem. Atualmente, a geração de imagem só está disponível com a api-version=2023-06-01-preview.

GET https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
operation-id string Obrigatório O GUID que identifica a solicitação de geração de imagem original.

Versões com suporte

Solicitação de exemplo

curl -X GET "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

Exemplo de resposta

Ao ser bem-sucedida, a operação retorna um código de status 200 e um objeto JSON de OperationResponse. O campo de status pode ser "notRunning" (a tarefa está na fila de espera, mas ainda não foi iniciada), "running", "succeeded", "canceled" (a tarefa excedeu o tempo limite), "failed" ou "deleted". Um status succeeded indica que a imagem gerada está disponível para download no URL fornecido. Se várias imagens foram geradas, seus URLs serão todos retornados no campo result.data.

{
  "created": 1685064331,
  "expires": 1685150737,
  "id": "4b755937-3173-4b49-bf3f-da6702a3971a",
  "result": {
    "data": [
      {
        "url": "<URL_TO_IMAGE>"
      },
      {
        "url": "<URL_TO_NEXT_IMAGE>"
      },
      ...
    ]
  },
  "status": "succeeded"
}

Excluir uma imagem gerada do servidor (versão prévia do DALL-E 2)

Você pode usar a ID da operação retornada pela solicitação para excluir a imagem correspondente do servidor do Azure. As imagens geradas são excluídas automaticamente após 24 horas por padrão, mas você pode disparar a exclusão mais cedo, se desejar.

DELETE https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
operation-id string Obrigatório O GUID que identifica a solicitação de geração de imagem original.

Versões com suporte

Solicitação de exemplo

curl -X DELETE "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

Resposta

A operação retornará um código de status 204 se for bem-sucedida. Essa API só terá sucesso se a operação estiver em um estado final (não running).

Conversão de fala em texto

Você pode usar um modelo Whisper no Serviço OpenAI do Azure para transcrição de fala em texto ou tradução de fala. Para obter mais informações sobre como usar um modelo Whisper, consulte o início rápido e a Visão geral do modelo Whisper.

Solicitar uma transcrição da conversão de fala em texto

Transcrever um arquivo de áudio.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/transcriptions?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
deployment-id string Obrigatório O nome da sua implantação do modelo Whisper, como MyWhisperDeployment. Você deve implantar primeiro um modelo Whisper antes de poder fazer chamadas.
api-version string Obrigatório A versão da API a ser usada para esta operação. Esse valor segue o formato AAAA-MM-DD.

Versões com suporte

Corpo da solicitação

Parâmetro Type Obrigatório? Padrão Descrição
file file Sim N/D O objeto de arquivo de áudio (não o nome do arquivo) a ser transcrever, em um destes formatos: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav ou webm.

O limite de tamanho do arquivo para o modelo Whisper no Serviço OpenAI do Azure é de 25 MB. Se você precisar transcrever um arquivo com mais de 25 MB, divida-o em partes. Alternativamente, você pode usar a API de transcrição em lote da Fala de IA do Azure.

Você pode obter os arquivos de áudio de amostra no repositório do SDK de Fala de IA do Azure no GitHub.
language string Não Nulo O idioma do áudio de entrada, como fr. O fornecimento da linguagem de entrada no formato ISO-639-1 melhora a precisão e a latência.

Para obter a lista de idiomas com suporte, consulte a documentação da OpenAI.
prompt string Não Nulo Um texto opcional para guiar o estilo do modelo ou continuar um segmento de áudio anterior. O prompt deve corresponder ao idioma do áudio.

Para obter mais informações sobre os prompts, incluindo os exemplos de casos de uso, consulte a documentação da OpenAI.
response_format string Não json O formato da saída da transcrição, em uma destas opções: json, text, srt, verbose_json ou vtt.

O valor padrão é json.
temperature number Não 0 A temperatura da amostragem, entre 0 e 1.

Valores mais altos, como 0,8, tornam a saída mais aleatória, enquanto valores mais baixos, como 0,2, a tornam mais focada e determinista. Se for definido como 0, o modelo usa o log probabilidade para aumentar automaticamente a temperatura até que determinados limites sejam atingidos.

O valor padrão é 0.

Solicitação de exemplo

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/transcriptions?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "language=en" \
  -F "prompt=The transcript contains zoology terms and geographical locations." \
  -F "temperature=0" \
  -F "response_format=srt"

Exemplo de resposta

1
00:00:00,960 --> 00:00:07,680
The ocelot, Lepardus paradalis, is a small wild cat native to the southwestern United States,

2
00:00:07,680 --> 00:00:13,520
Mexico, and Central and South America. This medium-sized cat is characterized by

3
00:00:13,520 --> 00:00:18,960
solid black spots and streaks on its coat, round ears, and white neck and undersides.

4
00:00:19,760 --> 00:00:27,840
It weighs between 8 and 15.5 kilograms, 18 and 34 pounds, and reaches 40 to 50 centimeters

5
00:00:27,840 --> 00:00:34,560
16 to 20 inches at the shoulders. It was first described by Carl Linnaeus in 1758.

6
00:00:35,360 --> 00:00:42,880
Two subspecies are recognized, L. p. paradalis and L. p. mitis. Typically active during twilight

7
00:00:42,880 --> 00:00:48,480
and at night, the ocelot tends to be solitary and territorial. It is efficient at climbing,

8
00:00:48,480 --> 00:00:54,480
leaping, and swimming. It preys on small terrestrial mammals such as armadillo, opossum,

9
00:00:54,480 --> 00:00:56,480
and lagomorphs.

Solicitar uma tradução da conversão de fala em texto

Traduz um arquivo de áudio de outro idioma para o inglês. Para obter a lista de idiomas com suporte, consulte a documentação da OpenAI.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/translations?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
deployment-id string Obrigatório O nome da sua implantação do modelo Whisper, como MyWhisperDeployment. Você deve implantar primeiro um modelo Whisper antes de poder fazer chamadas.
api-version string Obrigatório A versão da API a ser usada para esta operação. Esse valor segue o formato AAAA-MM-DD.

Versões com suporte

Corpo da solicitação

Parâmetro Type Obrigatório? Padrão Descrição
file file Sim N/D O objeto de arquivo de áudio (não o nome do arquivo) a ser transcrito, em um destes formatos: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav ou webm.

O limite de tamanho do arquivo para o modelo do OpenAI do Azure Whisper é de 25 MB. Se você precisar transcrever um arquivo com mais de 25 MB, divida-o em partes.

Você pode fazer o download de arquivos de áudio de amostra do repositório do SDK de Fala de IA do Azure no GitHub.
prompt string Não Nulo Um texto opcional para guiar o estilo do modelo ou continuar um segmento de áudio anterior. O prompt deve corresponder ao idioma do áudio.

Para obter mais informações sobre os prompts, incluindo os exemplos de casos de uso, consulte a documentação da OpenAI.
response_format string Não json O formato da saída da transcrição, em uma destas opções: json, text, srt, verbose_json ou vtt.

O valor padrão é json.
temperature number Não 0 A temperatura da amostragem, entre 0 e 1.

Valores mais altos, como 0,8, tornam a saída mais aleatória, enquanto valores mais baixos, como 0,2, a tornam mais focada e determinista. Se for definido como 0, o modelo usa o log probabilidade para aumentar automaticamente a temperatura até que determinados limites sejam atingidos.

O valor padrão é 0.

Solicitação de exemplo

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/translations?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "temperature=0" \
  -F "response_format=json"

Exemplo de resposta

{
  "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}

Conversão de texto em fala

Sintetizar a conversão de texto em fala.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/speech?api-version={api-version}

Parâmetros de caminho

Parâmetro Type Necessário? Descrição
your-resource-name string Obrigatório O nome do seu recurso OpenAI do Azure.
deployment-id string Obrigatório O nome da implantação do modelo de conversão de texto em fala, como MyTextToSpeechDeployment. Você precisa primeiro implantar um modelo de conversão de texto em fala (como tts-1 ou tts-1-hd) antes de fazer chamadas.
api-version string Obrigatório A versão da API a ser usada para esta operação. Esse valor segue o formato AAAA-MM-DD.

Versões com suporte

Corpo da solicitação

Parâmetro Type Obrigatório? Padrão Descrição
model string Sim N/D Um dos modelos TTS disponíveis: tts-1 ou tts-1-hd
input string Sim N/D O texto para o qual gerar áudio. O comprimento máximo é de 4.096 caracteres. Especifique o texto de entrada no idioma de sua escolha.1
voice string Sim N/D A voz a ser usada ao gerar o áudio. As vozes com suporte são alloy, echo, fable, onyx, nova e shimmer. As visualizações das vozes estão disponíveis no Guia de conversão de texto em fala do OpenAI.

1 Os modelos de conversão de texto em fala geralmente dão suporte aos mesmos idiomas que o modelo Whisper. Para obter a lista de idiomas com suporte, consulte a documentação da OpenAI.

Solicitação de exemplo

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/speech?api-version=2024-02-15-preview \
 -H "api-key: $YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "model": "tts-hd",
    "input": "I'm excited to try text to speech.",
    "voice": "alloy"
}' --output speech.mp3

Exemplo de resposta

A fala é retornada como um arquivo de áudio da solicitação anterior.

APIs de gerenciamento

O OpenAI do Azure é implantado como parte dos serviços de IA do Azure. Todos os serviços de IA do Azure dependem do mesmo conjunto de APIs de gerenciamento para operações de criação, atualização e exclusão. As APIs de gerenciamento também são usadas para implantar modelos em um recurso de OpenAI do Azure.

Documentação de referência das APIs de gerenciamento

Próximas etapas

Saiba mais sobre Modelos e ajuste fino com a API REST. Saiba mais sobre os modelos subjacentes que alimentam o OpenAI do Azure.