你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure OpenAI 服务 REST API 参考

  • 项目

本文详细介绍了 Azure OpenAI 的推理 REST API 端点。

身份验证

Azure OpenAI 提供两种身份验证方法。 可以使用 API 密钥或 Microsoft Entra ID。

  • API 密钥身份验证：对于这种类型的身份验证，所有 API 请求都必须在 api-key HTTP 标头中包含 API 密钥。 本快速入门提供有关如何通过此类身份验证进行调用的指南。

  • Microsoft Entra ID 身份验证：可以使用 Microsoft Entra 令牌对 API 调用进行身份验证。 身份验证令牌作为 Authorization 标头包含在请求中。 提供的令牌必须以 Bearer 开头，例如 Bearer YOUR_AUTH_TOKEN。 可以阅读有关如何使用 Microsoft Entra ID 进行身份验证的操作指南。

REST API 版本控制

服务 API 使用 api-version 查询参数进行版本控制。 所有版本都遵循 YYYY-MM-DD 日期结构。 例如：

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

完成

通过完成操作，模型将根据提供的提示生成一个或多个预测完成。 该服务还可以返回每个位置的替代令牌的概率。

创建完成

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
deployment-id 字符串 必需 部署模型时选择的部署名称。
api-version string 必需 要用于此操作的 API 版本。 它遵循 YYYY-MM-DD 格式。

支持的版本

请求正文

参数 类型 必需？ 默认 说明
prompt 字符串或数组 可选 <\|endoftext\|> 生成一个或多个完成的提示，其编码为字符串或字符串数组。 <\|endoftext\|> 是模型在训练期间看到的文档分隔符，因此如果未指定提示，模型就会像从新文档的开头一样生成。
max_tokens integer 可选 16 在完成中生成的最大令牌数。 提示加上 max_tokens 的令牌计数不能超过模型的上下文长度。 除最新模型（它支持 4096 个令牌）外，大多数模型的上下文长度为 2048 个令牌。
temperature 数字 可选 1 要使用的采样温度，介于 0 和 2 之间。 较高的值意味着模型将承担更多风险。 对于更具创意的应用程序，请尝试将值设为 0.9，对于具有明确定义答案的应用程序，将值设为 0 (argmax sampling) 。 我们通常建议更改此设置或 top_p，但不要同时更改这两者。
top_p 数字 可选 1 温度采样的替代方法，称为核采样，其中模型考虑具有 top_p 概率质量的令牌的结果。 所以 0.1 意味着只考虑包含前 10% 概率质量的令牌。 我们通常建议更改此设置或温度，但不要同时更改这两者。
logit_bias map 可选 Null 修改指定令牌在完成中出现的可能性。 接受 json 对象，该对象将令牌（由其在 GPT tokenizer 中的令牌 ID 指定）映射到从 -100 到 100 的关联偏差。 可以使用此 tokenizer 工具（适用于 GPT-2 和 GPT-3）将文本转换为令牌 ID。 在数学上，采样之前会将偏差添加到由模型生成的 logit 中。 具体效果因模型而异，但 -1 和 1 之间的值会减少或增加选择的可能性；-100 或 100 等值会导致相关令牌的禁止或独占选择。 例如，可以传递 {"50256": -100} 以防止生成 <|endoftext|> 令牌。
user 字符串 可选 表示最终用户的唯一标识符，可帮助监视和检测滥用行为
n integer 可选 1 要为每个提示生成的完成数。 注意：由于此参数会生成许多完成，因此可能会快速消耗你的令牌配额。 谨慎使用并确保对 max_tokens 和 stop 进行了合理的设置。
stream boolean 可选 False 是否流式传输回部分进度。 如果设置，令牌将在可用时作为仅数据服务器发送的事件发送，流由 data：[DONE] 消息终止。
logprobs integer 可选 Null 包含有关 logprobs 最有可能的令牌和已选择的令牌的日志概率。 例如，如果 logprobs 为 10，则 API 将返回包含 10 个最有可能的令牌的列表。 API 将始终返回采样令牌的 logprob，因此响应中可能最多有 logprobs+1 个元素。 此参数不能与 gpt-35-turbo 一起使用。
suffix string 可选 Null 插入的文本完成后的后缀。
echo boolean 可选 False 除了完成之外，还要回显提示。 此参数不能与 gpt-35-turbo 一起使用。
stop 字符串或数组 可选 Null 最多四个序列，其中 API 将停止生成进一步的令牌。 返回的文本不包含停止序列。 对于 GPT-4 Turbo with Vision，最多支持两个序列。
presence_penalty 数字 可选 0 介于 -2.0 和 2.0 之间的数字。 正值会根据它们到目前为止是否在文本中出现来惩罚新令牌，从而增加模型谈论新话题的可能性。
frequency_penalty 数字 可选 0 介于 -2.0 和 2.0 之间的数字。 正值会根据它们到目前为止在文本中的现有频率来惩罚新令牌，从而降低模型逐字重复同一行的可能性。
best_of integer 可选 1 在服务器端生成 best_of 完成并返回“最佳”（每个令牌的日志概率最低的参数）。 无法流式传输结果。 与 n 一起使用时，best_of 控制候选完成数，n 指定返回的完成数，best_of 的值必须大于 n 的值。 注意：由于此参数会生成许多完成，因此可能会快速消耗你的令牌配额。 谨慎使用并确保对 max_tokens 和 stop 进行了合理的设置。 此参数不能与 gpt-35-turbo 一起使用。

示例请求

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
}"

示例响应

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

在示例响应中，finish_reason 等于 stop。 如果 finish_reason 等于 content_filter，请参阅我们的内容筛选指南，了解发生此情况的原因。

嵌入

获取给定输入的向量表示形式，该输入可由机器学习模型和其他算法轻松使用。

注意

OpenAI 目前允许使用 text-embedding-ada-002 输入更多的数组。 对于 text-embedding-ada-002 (Version 2)，Azure OpenAI 目前支持最多 16 个输入数组。 两者都要求此模型的每个 API 请求的最大输入令牌限制保持在 8191 之下。

创建嵌入

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
deployment-id 字符串 必需 模型部署的名称。 必须先部署模型，然后才能进行调用。
api-version string 必需 要用于此操作的 API 版本。 它遵循 YYYY-MM-DD 格式。

支持的版本

请求正文

参数 类型 必需？ 默认 说明
input 字符串或数组 是 空值 获取嵌入的输入文本，编码为数组或字符串。 输入令牌的数量因所使用的模型而异。 仅 text-embedding-ada-002 (Version 2) 支持数组输入。
user string 否 Null 表示最终用户的唯一标识符。 这将帮助 Azure OpenAI 监视和检测滥用行为。 不要传递 PII 标识符，而是使用伪名化值，例如 GUID
encoding_format string 否 float 嵌入的返回格式。 可以为 float 或 base64。 默认为 float。

[在 2024-03-01-preview 中添加]。
dimensions integer 否 生成的输出嵌入应有的维度数。 仅在 text-embedding-3 及更高版本中受支持。

[在 2024-03-01-preview 中添加]

示例请求

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...\"}"

示例响应

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

聊天完成

使用 GPT-35-Turbo 和 GPT-4 模型创建聊天消息补全内容。

创建聊天完成

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
deployment-id 字符串 必需 模型部署的名称。 必须先部署模型，然后才能进行调用。
api-version string 必需 要用于此操作的 API 版本。 这遵循 YYYY-MM-DD 或 YYYY-MM-DD-preview 格式。

支持的版本

请求正文

请求正文由一系列消息组成。 该模型将使用早期消息作为上下文生成对最后一条消息的响应。

参数 类型 必需？ 默认 说明
messages 数组 是 空值 与此聊天完成请求关联的系列消息。 它应将以前的消息包含在对话中。 每条消息都包含 role 和 content。
role string 是 空值 指示谁正在提供当前消息。 可以是 system、user、assistant、tool 或 function。
content 字符串或数组 是 空值 消息的内容。 它必须是字符串，除非在启用了视觉的方案中。 如果它是 user 消息的一部分，使用 GPT-4 Turbo with Vision 模型以及最新的 API 版本，则 content 必须是一个结构数组，其中每个项代表文本或图像：
  • text：输入文本表示为具有以下属性的结构：
    • type = "text"
    • text = 输入文本
  • images：输入图像表示为具有以下属性的结构：
    • type = "image_url"
    • image_url = 具有以下属性的结构：
      • url = 图像 URL
      • （可选）detail = high、low 或 auto
contentPart object 否 空值 用户的多模式消息的一部分。 它可以是文本类型或图像类型。 如果为文本，则为文本字符串。 如果为图像，它将是一个 contentPartImage 对象。
contentPartImage object 否 空值 表示用户上传的图像。 它具有一个 url 属性，是图像的 URL 或 base 64 编码的图像数据。 它还具有一个 detail 属性，可以是 auto、low 或 high。
enhancements object 否 空值 表示为聊天请求的视觉增强功能。 它具有 grounding 和 ocr 属性，每个属性都具有布尔 enabled 属性。 使用这些内容请求 OCR 服务和/或对象检测/定位服务[此预览版参数在 2024-02-01 GA API 中不可用]。
dataSources object 否 空值 表示其他资源数据。 视觉增强需要计算机视觉资源数据。 它有一个应为 "AzureComputerVision" 的 type 属性，具有 endpoint 的 parameters 属性，以及 key 属性。 这些字符串应设置为计算机视觉资源的终结点 URL 和访问密钥。

示例请求

纯文本聊天

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?"}]}'

通过视觉聊天

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" } }]}]}'

带有视觉的增强聊天

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"}]}]}'

示例响应

{
    "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
        }
    ]
}

已为易读性调整输出格式，实际输出是一个没有换行符的单个文本块。

在示例响应中，finish_reason 等于 stop。 如果 finish_reason 等于 content_filter，请参阅我们的内容筛选指南，了解发生此情况的原因。

重要

随着 API 的 2023-12-01-preview 版本的发布，functions 和 function_call 参数已被弃用。 functions 的替代项是 tools 参数。 function_call 的替代项是 tool_choice 参数。 仅 gpt-35-turbo (1106) 和 gpt-4 (1106-preview)（也称为 GPT-4 Turbo 预览版）支持在 2023-12-01-preview 中引入的并行函数调用。

参数 类型 必需？ 默认 说明
messages array 必须 与此聊天补全请求关联的上下文消息的集合。 典型的用法从系统角色的聊天消息开始，该消息提供有关助手行为的说明，然后是“用户”和“助手”角色之间的交替消息。
temperature 数字 可选 1 要使用的采样温度，介于 0 和 2 之间。 较高的值（如 0.8）将使输出更随机，而较小的值（如 0.2）将使输出更集中且更具确定性 我们通常建议更改此设置或 top_p，但不要同时更改两者。
n integer 可选 1 要为每个输入消息生成的聊天完成选项数。
stream boolean 可选 false 如果设置此选项，将发送部分消息增量，如在 ChatGPT 中一样。 令牌将在可用时作为仅数据服务器发送的事件发送，流由 data: [DONE] 消息终止。
stop 字符串或数组 可选 Null 最多四个序列，其中 API 将停止生成更多令牌。
max_tokens integer 可选 inf 生成的答案允许的最大令牌数。 默认情况下，模型可返回的标记数将为（4096 - 提示标记）。
presence_penalty 数字 可选 0 介于 -2.0 和 2.0 之间的数字。 正值会根据它们到目前为止是否在文本中出现来惩罚新令牌，从而增加模型谈论新话题的可能性。
frequency_penalty 数字 可选 0 介于 -2.0 和 2.0 之间的数字。 正值会根据它们到目前为止在文本中的现有频率来惩罚新令牌，从而降低模型逐字重复同一行的可能性。
logit_bias 对象 (object) 可选 Null 修改指定令牌在完成中出现的可能性。 接受 json 对象，该对象将标记（由 tokenizer 中的标记 ID 指定）映射到从 -100 到 100 的相关偏差值。 在数学上，采样之前会将偏差添加到由模型生成的 logit 中。 具体效果因模型而异，但 -1 和 1 之间的值会减少或增加选择的可能性；-100 或 100 等值会导致相关令牌的禁止或独占选择。
user string 可选 表示最终用户的唯一标识符，可帮助 Azure OpenAI 监视和检测滥用行为。
function_call 可选 [Deprecated in 2023-12-01-preview replacement parameter is tools_choice]控制模型如何响应函数调用。 “none”表示模型不调用函数，并对最终用户做出响应。 auto 表示模型可以在最终用户或调用函数之间进行选择。 通过 {"name": "my_function"} 指定特定函数会强制模型调用该函数。 当不存在任何函数时，“none”是默认值。 如果存在函数，则 auto 是默认值。 此参数需要 API 版本 2023-07-01-preview
functions FunctionDefinition[] 可选 [Deprecated in 2023-12-01-preview replacement paremeter is tools] 模型可为其生成 JSON 输入的函数列表。 此参数需要 API 版本 2023-07-01-preview
tools 字符串（工具的类型。仅支持 function。） 可选 模型可调用的工具列表。 目前，仅支持函数作为工具。 使用它可以提供函数列表，模型可能为其生成 JSON 输入。 此参数需要 API 版本 2023-12-01-preview
tool_choice 字符串或对象 可选 当不存在任何函数时，none 是默认值。 如果存在函数，则 auto 是默认值。 控制模型调用的函数（如有）。 None 表示模型不会调用函数，而是生成消息。 auto 表示模型可以在生成消息和调用函数之间进行选择。 通过 {"type: "function", "function": {"name": "my_function"}} 指定特定函数会强制模型调用该函数。 此参数需要 API 2023-12-01-preview 或更高版本。

ChatMessage

聊天补全交互中的单个角色属性化消息。

名称 Type 描述
内容 string 与此消息有效负载关联的文本。
function_call FunctionCall 应调用的函数的名称和参数，由模型生成。
name string 此消息的作者的 name。 如果角色为 function，则 name 为必填项，并且它应该是其响应在 content 中的函数的名称。 可能包含 a-z、A-Z、0-9 和下划线，最大长度为 64 个字符。
role ChatRole 与此消息有效负载关联的角色

ChatRole

聊天补全交互中消息的预期用途的说明。

名称 Type 描述
assistant string 对系统指示的用户提示输入做出响应的角色。
函数 string 为聊天补全提供函数结果的角色。
system string 指示或设置助手行为的角色。
user string 为聊天补全提供输入的角色。

函数

这与 API 版本 2023-12-01-preview 中添加的 tools 参数一起使用。

名称 Type 说明
description string 函数作用的描述，由模型用于选择何时以及如何调用函数
name string 要调用的函数的名称。 必须是 a-z、A-z、0-9，或包含下划线和短划线，最大长度为 64
parameters object 函数接受的参数，被描述为 JSON 架构对象。 有关格式的文档，请参阅 JSON 模式引用。”

FunctionCall-Deprecated

应调用的函数的名称和参数，由模型生成。 这需要 API 版本 2023-07-01-preview

名称 Type 描述
参数 string 用于调用函数的参数，由模型以 JSON 格式生成。 该模型并非始终生成有效的 JSON，并且可能会构造函数架构未定义的参数。 在调用函数之前验证代码中的参数。
name string 要调用的函数名称。

FunctionDefinition-Deprecated

调用方指定的函数的定义，聊天补全可能会调用该函数以响应匹配的用户输入。 这需要 API 版本 2023-07-01-preview

名称 Type 说明
description string 函数操作的说明。 当选择函数并解释其参数时，模型将使用此说明。
name string 要调用的函数的名称。
parameters 函数接受的参数，被描述为 JSON 架构对象。

完成扩展

聊天完成的扩展，例如数据上的 Azure OpenAI。

重要

以下信息适用于 API 的版本 2023-12-01-preview。 这不是 API 的当前版本。 若要查找最新的参考文档，请参阅 Azure OpenAI On Your Data 参考。

使用聊天完成扩展

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
deployment-id 字符串 必需 模型部署的名称。 必须先部署模型，然后才能进行调用。
api-version string 必需 要用于此操作的 API 版本。 它遵循 YYYY-MM-DD 格式。

支持的版本

示例请求

可以使用 Azure AI 搜索、Azure Cosmos DB for MongoDB vCore、Pinecone 和 Elasticsearch 发出请求。 有关详细信息，请参阅数据中的 Azure OpenAI。

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 for 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 机器学习
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"
        }
      }
    }
  ]
}
'

示例响应

{
    "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
                }
            ]
        }
    ]
}
参数 类型 必需？ 默认 说明
messages array 必须 Null 要以聊天格式为其生成聊天完成的消息。
dataSources array 必须 要用于数据功能上 Azure OpenAI 的数据源。
temperature 数字 可选 0 要使用的采样温度，介于 0 和 2 之间。 较高的值（如 0.8）将使输出更随机，而较小的值（如 0.2）将使输出更集中且更具确定性 我们通常建议更改此设置或 top_p，但不要同时更改两者。
top_p 数字 可选 1 温度采样的替代方法，称为核心采样，其中模型将考虑具有 top_p 概率质量的令牌的结果。 所以 0.1 意味着只考虑包含前 10% 概率质量的令牌。 我们通常建议更改此设置或温度，但不要同时更改这两者。
stream boolean 可选 false 如果设置，将发送部分消息增量，如在 ChatGPT 中一样。 令牌将在可用时作为仅限数据的服务器发送的事件发送，并且流式传输由 "messages": [{"delta": {"content": "[DONE]"}, "index": 2, "end_turn": true}] 消息终止
stop 字符串或数组 可选 Null 最多 2 个序列，其中 API 将停止生成更多令牌。
max_tokens integer 可选 1000 生成的答案允许的最大令牌数。 默认情况下，模型可返回的令牌数为 4096 - prompt_tokens。

以下参数可用于 dataSources 中的 parameters 字段内。

参数 类型 必需？ 默认 说明
type 字符串 必须 Null 要用于数据功能上 Azure OpenAI 的数据源。 对于 Azure AI 搜索，该值为 AzureCognitiveSearch。 对于 Azure Cosmos DB for MongoDB vCore，该值为 AzureCosmosDB。 对于 Elasticsearch，该值为 Elasticsearch。 对于 Azure 机器学习，该值为 AzureMLIndex。 对于 Pinecone，该值为 Pinecone。
indexName string 必须 Null 要使用的搜索索引。
inScope boolean 可选 true 如果设置，此值将限制特定于基础数据内容的响应。
topNDocuments 数字 可选 5 指定用于生成响应的数据索引中评分最高的文档数。 如果文档短，或者你想要提供更多上下文，则可能需要增加该值。 这是 Azure OpenAI 工作室中的“检索的文档”参数。
semanticConfiguration string 可选 Null 语义搜索配置。 只有在 queryType 设置为 semantic 或 vectorSemanticHybrid 时才需要。
roleInformation string 可选 Null 为模型提供有关它应该如何运行以及在生成响应时应引用的上下文的说明。 对应于 Azure OpenAI Studio 中的“系统消息”。 有关详细信息，请参阅使用数据。 存在 100 个令牌的限制，并将计入整体令牌限制。
filter string 可选 Null 用于限制对敏感文档的访问的筛选器模式
embeddingEndpoint string 可选 Null Ada 嵌入模型部署的终结点 URL，通常采用 https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2023-05-15 格式。 与 embeddingKey 参数一起用于专用网络和专用终结点外部的矢量搜索。
embeddingKey string 可选 Null Ada 嵌入模型部署的 API 密钥。 与 embeddingEndpoint 一起用于专用网络和专用终结点外部的矢量搜索。
embeddingDeploymentName string 可选 Null Ada 在同一 Azure OpenAI 资源中嵌入模型部署名称。 用于矢量搜索，而不是使用 embeddingEndpoint 和 embeddingKey。 仅当定义 embeddingEndpoint 和 embeddingKey 参数时，才应使用。 提供此参数后，数据上的 Azure OpenAI 将使用内部调用来评估 Ada 嵌入模型，而不是调用 Azure OpenAI 终结点。 这样，便可以在专用网络和专用终结点中使用矢量搜索。 无论是否定义此参数，计费保持不变。 从 API 版本 2023-06-01-preview 及更高版本开始，在嵌入模型可用的地区可用。
strictness 数字 可选 3 设置阈值以将文档分类为与查询相关。 提高该值意味着相关性的阈值更高，并为响应筛选出相关程度较低的文档。 将此值设置得过高可能会导致模型由于可用文档有限而无法生成响应。

Azure AI 搜索参数

以下参数用于 Azure AI 搜索。

参数 类型 必需？ 默认 说明
endpoint 字符串 必须 Null 仅限 Azure AI 搜索。 数据源终结点。
key 字符串 必须 Null 仅限 Azure AI 搜索。 服务的 Azure AI 搜索管理密钥之一。
queryType string 可选 简单 指示用于 Azure AI 搜索的查询选项。 可用类型：simple、semantic、vector、vectorSimpleHybrid、vectorSemanticHybrid。
fieldsMapping dictionary 对于 Azure AI 搜索是可选的。 Null 定义在添加数据源时要映射的字段。

以下参数在 authentication 字段内使用，使你能够在不使用公用网络访问的情况下使用 Azure OpenAI。

参数 类型 必需？ 默认 说明
type 字符串 必须 null 身份验证类型。
managedIdentityResourceId string 必须 Null 用于进行身份验证的用户分配托管标识的资源 ID。 
"authentication": {
  "type": "UserAssignedManagedIdentity",
  "managedIdentityResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{resource-name}"
},

fieldsMapping 字段内使用以下参数。

参数 类型 必需？ 默认 说明
titleField 字符串 可选 Null 索引中包含每个文档的原始标题的字段。
urlField string 可选 Null 索引中包含每个文档的原始 URL 的字段。
filepathField string 可选 Null 索引中包含每个文档的原始文件名的字段。
contentFields dictionary 可选 Null 索引中包含每个文档的主文本内容的字段。
contentFieldsSeparator string 可选 Null 内容字段的分隔符。 默认使用 \n。 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n"
}

以下参数用于可选 embeddingDependency 参数内，该参数包含基于同一 Azure OpenAI 资源中内部嵌入模型部署名称的矢量化源的详细信息。

参数 类型 必需？ 默认 说明
deploymentName 字符串 可选 Null 要使用的向量化源的类型。
type string 可选 Null 嵌入模型部署名称，位于同一 Azure OpenAI 资源中。 这样便可以在没有 Azure OpenAI API 密钥和 Azure OpenAI 公用网络访问的情况下使用矢量搜索。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Azure Cosmos DB for MongoDB vCore 参数

以下参数用于 Azure Cosmos DB for MongoDB vCore。

参数 类型 必需？ 默认 说明
type（在 authentication 中找到） string 必须 Null 仅限 Azure Cosmos DB for MongoDB vCore。 使用的身份验证。 对于 Azure Cosmos Mongo vCore，该值为 ConnectionString
connectionString string 必须 Null 仅限 Azure Cosmos DB for MongoDB vCore。 用于对 Azure Cosmos Mongo vCore 帐户进行身份验证的连接字符串。
databaseName string 必须 Null 仅限 Azure Cosmos DB for MongoDB vCore。 Azure Cosmos Mongo vCore 数据库名称。
containerName string 必须 Null 仅限 Azure Cosmos DB for MongoDB vCore。 数据库中的 Azure Cosmos Mongo vCore 容器名称。
type（在 embeddingDependencyType 中找到） string 必须 null 指示嵌入模型依赖项。
deploymentName（在 embeddingDependencyType 中找到） string 必须 null 嵌入模型部署名称。
fieldsMapping dictionary 对于 Azure Cosmos DB for MongoDB vCore 是必需的。 Null 索引数据列映射。 使用 Azure Cosmos DB for MongoDB vCore 时，需要指定 vectorFields 值，用于指示存储矢量的字段。

以下参数用于可选 embeddingDependency 参数内，该参数包含基于同一 Azure OpenAI 资源中内部嵌入模型部署名称的矢量化源的详细信息。

参数 类型 必需？ 默认 说明
deploymentName 字符串 可选 Null 要使用的向量化源的类型。
type string 可选 Null 嵌入模型部署名称，位于同一 Azure OpenAI 资源中。 这样便可以在没有 Azure OpenAI API 密钥和 Azure OpenAI 公用网络访问的情况下使用矢量搜索。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Elasticsearch 参数

以下参数用于 Elasticsearch。

参数 类型 必需？ 默认 说明
endpoint 字符串 必须 Null 用于连接到 Elasticsearch 的终结点。
indexName string 必须 Null Elasticsearch 索引的名称。
type（在 authentication 中找到） string 必须 Null 要使用的身份验证。 对于 Elasticsearch，该值为 KeyAndKeyId。
key（在 authentication 中找到） string 必须 Null 用于连接到 Elasticsearch 的密钥。
keyId（在 authentication 中找到） string 必须 Null 要使用的密钥 ID。 对于 Elasticsearch。

fieldsMapping 字段内使用以下参数。

参数 类型 必需？ 默认 说明
titleField 字符串 可选 Null 索引中包含每个文档的原始标题的字段。
urlField string 可选 Null 索引中包含每个文档的原始 URL 的字段。
filepathField string 可选 Null 索引中包含每个文档的原始文件名的字段。
contentFields dictionary 可选 Null 索引中包含每个文档的主文本内容的字段。
contentFieldsSeparator string 可选 Null 内容字段的分隔符。 默认使用 \n。
vectorFields dictionary 可选 Null 表示矢量数据的字段的名称 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n",
  "vectorFields": [
    "myVectorField"
  ]
}

以下参数用于可选 embeddingDependency 参数内，该参数包含基于同一 Azure OpenAI 资源中内部嵌入模型部署名称的矢量化源的详细信息。

参数 类型 必需？ 默认 说明
deploymentName 字符串 可选 Null 要使用的向量化源的类型。
type string 可选 Null 嵌入模型部署名称，位于同一 Azure OpenAI 资源中。 这样便可以在没有 Azure OpenAI API 密钥和 Azure OpenAI 公用网络访问的情况下使用矢量搜索。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Azure 机器学习参数

以下参数用于 Azure 机器学习。

参数 类型 必需？ 默认 说明
projectResourceId 字符串 必须 Null 项目资源 ID。
name string 必须 Null Azure 机器学习项目的名称。
version（在 authentication 中找到） string 必须 Null Azure 机器学习向量索引的版本。

以下参数用于可选 embeddingDependency 参数内，该参数包含基于同一 Azure OpenAI 资源中内部嵌入模型部署名称的矢量化源的详细信息。

参数 类型 必需？ 默认 说明
deploymentName 字符串 可选 Null 要使用的向量化源的类型。
type string 可选 Null 嵌入模型部署名称，位于同一 Azure OpenAI 资源中。 这样便可以在没有 Azure OpenAI API 密钥和 Azure OpenAI 公用网络访问的情况下使用矢量搜索。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Pinecone 参数

以下参数用于 Pinecone。

参数 类型 必需？ 默认 说明
type（在 authentication 中找到） string 必须 Null 要使用的身份验证。 对于 Pinecone，该值为 APIKey。
apiKey（在 authentication 中找到） string 必须 Null Pinecone 的 API 密钥。
environment string 必须 Null Pinecone 环境的名称。
indexName string 必须 null Pinecone 索引的名称。
embeddingDependency string 必须 Null 矢量搜索的嵌入依赖项。
type（在 embeddingDependency 中找到） string 必须 Null 依赖项的类型。 对于 Pinecone，该值为 DeploymentName。
deploymentName（在 embeddingDependency 中找到） string 必须 null 部署的名称。
titleField（在 fieldsMapping 中找到） string 必须 Null 要用作标题的索引字段的名称。
urlField（在 fieldsMapping 中找到） string 必须 null 要用作 URL 的索引字段的名称。
filepathField（在 fieldsMapping 中找到） string 必须 null 要用作文件路径的索引字段的名称。
contentFields（在 fieldsMapping 中找到） string 必须 Null 应被视为内容的索引字段的名称。
vectorFields dictionary 可选 Null 表示矢量数据的字段的名称
contentFieldsSeparator（在 fieldsMapping 中找到） string 必须 Null 内容字段的分隔符。 默认使用 \n。

以下参数用于可选 embeddingDependency 参数内，该参数包含基于同一 Azure OpenAI 资源中内部嵌入模型部署名称的矢量化源的详细信息。

参数 类型 必需？ 默认 说明
deploymentName 字符串 可选 Null 要使用的向量化源的类型。
type string 可选 Null 嵌入模型部署名称，位于同一 Azure OpenAI 资源中。 这样便可以在没有 Azure OpenAI API 密钥和 Azure OpenAI 公用网络访问的情况下使用矢量搜索。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

启动引入作业（预览版）

提示

所选的 JOB_NAME 将用作索引名称。 请注意索引名称的约束。

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 }'

示例响应

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

标头参数

参数 类型 必需？ 默认 说明
searchServiceEndpoint 字符串 必须 null 要在其中引入数据的搜索资源的终结点。
searchServiceAdminKey string 可选 Null 如果提供，密钥将用于向 searchServiceEndpoint 进行身份验证。 如果未提供，将使用 Azure OpenAI 资源的系统分配标识。 在这种情况下，系统分配的标识必须在搜索资源上分配“搜索服务参与者”角色。
storageConnectionString string 必须 null 输入数据所在的存储帐户的连接字符串。 必须在连接字符串中提供帐户密钥。 它应类似于 DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>
storageContainer string 必须 null 输入数据所在的容器的名称。
embeddingEndpoint string 可选 Null 如果使用语义搜索或仅关键字搜索，则不需要。 如果使用矢量、混合或混合 + 语义搜索，则需要它
embeddingKey string 可选 Null 嵌入终结点的密钥。 如果嵌入终结点不为空，则需要此操作。
url string 可选 Null 如果 URL 不为 null，则提供的 URL 将爬网到提供的存储容器中，然后相应地引入。

正文参数

参数 类型 必需？ 默认 说明
dataRefreshIntervalInMinutes 字符串 必须 0 数据刷新间隔（以分钟为单位）。 如果要在没有计划的情况下运行单个引入作业，请将此参数设置为 0。
completionAction string 可选 cleanUpAssets 作业完成后在引入过程中创建的资产会发生什么情况。 有效值为 cleanUpAssets or keepAllAssets进行求值的基于 SQL 语言的筛选器表达式。 keepAllAssets 将所有中间资产留给有兴趣查看中间结果的用户，这有助于调试资产。 作业完成后，cleanUpAssets 会删除资产。
chunkSize int 可选 1024 此数字定义引入流生成的每个区块中的最大令牌数。

列出引入作业（预览版）

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"

示例响应

{ 
    "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": [] 
        } 
    ] 
}

获取引入作业的状态（预览版）

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"

示例响应正文

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

图像生成

请求生成的映像 (DALL-E 3)

通过文本标题生成和检索一批图像。

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
deployment-id 字符串 必须 DALL-E 3 模型部署的名称，例如 MyDalle3。 必须先部署 DALL-E 3 模型，然后才能进行调用。
api-version string 必需 要用于此操作的 API 版本。 它遵循 YYYY-MM-DD 格式。

支持的版本

请求正文

参数 类型 必需？ 默认 说明
prompt 字符串 必须 所需图像的文本说明。 最大长度为 4000 个字符。
n integer 可选 1 要生成的图像数。 DALL-E 3 仅支持 n=1。
size string 可选 1024x1024 生成的图像的大小。 必须是 1792x1024、1024x1024 或 1024x1792。
quality string 可选 standard 生成的图像的质量。 必须是 hd 或 standard。
response_format string 可选 url 生成的图像的返回格式必须是 url（指向图像的 URL）或 b64_json（JSON 格式的 base64 字节代码）。
style string 可选 vivid 生成的图像的样式。 必须是 natural 或 vivid（对于超现实/戏剧性图像）。
user string 可选 表示最终用户的唯一标识符，可帮助监视和检测滥用行为。

示例请求

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"
  }'

示例响应

操作返回 202 状态代码和 GenerateImagesResponse JSON 对象，其中包含操作的 ID 和状态。

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

请求生成的图像 (DALL-E 2 预览版)

从文本描述文字生成一批图像。

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
api-version 字符串 必需 要用于此操作的 API 版本。 它遵循 YYYY-MM-DD 格式。

支持的版本

请求正文

参数 类型 必需？ 默认 说明
prompt 字符串 必须 所需图像的文本说明。 最大长度为 1000 个字符。
n integer 可选 1 要生成的图像数。 必须介于 1 和 5 之间。
size 字符串 可选 1024x1024 生成的图像的大小。 必须是 256x256、512x512 或 1024x1024。

示例请求

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
}'

示例响应

操作返回 202 状态代码和 GenerateImagesResponse JSON 对象，其中包含操作的 ID 和状态。

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

获取生成的图像结果 (DALL-E 2 预览版)

使用此 API 检索图像生成操作的结果。 映像生成目前仅适用于 api-version=2023-06-01-preview。

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
operation-id 字符串 必须 标识原始图像生成请求的 GUID。

支持的版本

示例请求

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}"

示例响应

成功后，操作将返回 200 状态代码和 OperationResponse JSON 对象。 status 字段可以是 "notRunning"（任务已排队但尚未启动）、"running"、"succeeded"、"canceled"（任务已超时）、"failed" 或 "deleted"。 succeeded 状态表示生成的图像可在给定 URL 处下载。 如果生成了多个图像，则它们的 URL 全部在 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"
}

从服务器中删除生成的图像 (DALL-E 2 预览版)

可以使用请求返回的操作 ID 从 Azure 服务器中删除相应的图像。 默认情况下，生成的图像会在 24 小时后自动删除，但如果需要，可以提前触发删除操作。

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
operation-id 字符串 必须 标识原始图像生成请求的 GUID。

支持的版本

示例请求

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}"

响应

如果成功，操作将返回 204 状态代码。 仅当操作处于结束状态（不是 running）时，此 API 才会成功。

语音转文本

可以在 Azure OpenAI 服务中使用 Whisper 模型进行语音转文本听录或语音翻译。 有关使用 Whisper 模型的详细信息，请参阅快速入门和 Whisper 模型概述。

请求语音转文本听录

转录音频文件。

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
deployment-id 字符串 必须 Whisper 模型部署的名称，例如 MyWhisperDeployment。 必须先部署 Whisper 模型，然后才能进行调用。
api-version string 必需 要用于此操作的 API 版本。 此值遵循 YYYY-MM-DD 格式。

支持的版本

请求正文

参数 类型 必需？ 默认 说明
file 文件 是 空值 音频文件对象（非文件名）采用以下格式之一进行转录：flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav 或 webm。

Azure OpenAI 服务中的 Whisper 模型的文件大小限制为 25 MB。 如果需要转录大于 25 MB 的文件，请将其拆分成区块。 或者，可以使用 Azure AI 语音批处理听录 API。

可以从 GitHub 上的 Azure AI 语音 SDK 存储库获取示例音频文件。
language string 否 Null 输入音频的语言，例如 fr。 以 ISO-639-1 格式提供输入语言可以提高准确性并减少延迟。

有关受支持语言的列表，请参阅 OpenAI 文档。
prompt string 否 Null 用于指导模型风格或继续之前的音频片段的可选文本。 提示应与音频语言匹配。

有关提示（包括示例用例）的详细信息，请参阅 OpenAI 文档。
response_format string 否 json 脚本输出的格式，采用以下选项之一：json、text、srt、verbose_json 或 vtt。

默认值为 json。
temperature 数字 否 0 采样温度，介于 0 和 1 之间。

较大的值（如 0.8）使输出更随机，而较小的值（如 0.2）使输出更集中且更具确定性。 如果设置为 0，则模型使用对数概率自动升高温度，直到达到特定阈值。

默认值为 0。

示例请求

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"

示例响应

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.

请求语音到文本的转换

将音频文件从其他语言翻译成英语。 有关受支持语言的列表，请参阅 OpenAI 文档。

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
deployment-id 字符串 必须 Whisper 模型部署的名称，例如 MyWhisperDeployment。 必须先部署 Whisper 模型，然后才能进行调用。
api-version string 必需 要用于此操作的 API 版本。 此值遵循 YYYY-MM-DD 格式。

支持的版本

请求正文

参数 类型 必需？ 默认 说明
file 文件 是 空值 音频文件对象（非文件名）采用以下格式之一进行转录：flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav 或 webm。

Azure OpenAI Whisper 模型的文件大小限制为 25 MB。 如果需要转录大于 25 MB 的文件，请将其拆分成区块。

可以从 GitHub 上的 Azure AI 语音 SDK 存储库下载示例音频文件。
prompt string 否 Null 用于指导模型风格或继续之前的音频片段的可选文本。 提示应与音频语言匹配。

有关提示（包括示例用例）的详细信息，请参阅 OpenAI 文档。
response_format string 否 json 脚本输出的格式，采用以下选项之一：json、text、srt、verbose_json 或 vtt。

默认值为 json。
temperature 数字 否 0 采样温度，介于 0 和 1 之间。

较大的值（如 0.8）使输出更随机，而较小的值（如 0.2）使输出更集中且更具确定性。 如果设置为 0，则模型使用对数概率自动升高温度，直到达到特定阈值。

默认值为 0。

示例请求

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"

示例响应

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

文本到语音转换

将文本合成为语音。

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

路径参数

参数 类型 必需？ 说明
your-resource-name 字符串 必需 Azure OpenAI 资源的名称。
deployment-id 字符串 必须 文本转语音模型部署的名称，例如 MyTextToSpeechDeployment。 必须先部署文本转语音模型（例如 tts-1 或 tts-1-hd），然后才能进行调用。
api-version string 必需 要用于此操作的 API 版本。 此值遵循 YYYY-MM-DD 格式。

支持的版本

请求正文

参数 类型 必需？ 默认 说明
model 字符串 是 空值 可用的 TTS 模型之一：tts-1 或 tts-1-hd
input string 是 空值 要为其生成音频的文本。 最大长度为 4096 个字符。 使用所选语言指定输入文本。1
voice string 是 空值 生成音频时要使用的语音。 支持的语音为 alloy、echo、fable、onyx、nova 和 shimmer。 OpenAI 文本转语音指南中提供了语音预览。

1 文本转语音模型通常与 Whisper 模型支持相同的语言。 有关受支持语言的列表，请参阅 OpenAI 文档。

示例请求

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

示例响应

语音作为上一请求中的音频文件返回。

管理 API

Azure OpenAI 作为 Azure AI 服务的一部分进行部署。 所有 Azure AI 服务都依赖于同一组管理 API 来执行创建、更新和删除操作。 管理 API 还用于在 Azure OpenAI 资源中部署模型。

管理 API 参考文档

后续步骤

了解模型和微调与 REST API。 详细了解为 Azure OpenAI 提供支持的基础模型。