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

数据 API 引用的 Azure OpenAI

2025-05-02

本文提供了新的基于自有数据的 Azure OpenAI API 的 Python 和 REST 参考文档。最新的 API 版本为 2024-05-01-previewSwagger spec。

注意

自 API 版本 2024-02-15-preview 起，与早期 API 版本相比，我们引入了以下中断性变更：

API 路径从 /extensions/chat/completions 更改为 /chat/completions。
属性键和枚举值的命名约定从从驼峰式大小写更改为蛇形大小写。示例：deploymentName 更改为 deployment_name。
数据源类型 AzureCognitiveSearch 更改为 azure_search。
引文和意向从助手消息的上下文工具消息移动到助手消息的上下文根级别，其中定义了显式架构。

POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

支持的版本

2024-02-15-preview Swagger spec。
2024-02-01 Swagger spec。
2024-05-01-preview Swagger 规范

注意

支持 Pinecone 和 Elasticsearch 的预览版。

URI 参数

名称	在	类型	必需	说明
`deployment-id`	路径	字符串	真实	指定要用于此请求的聊天补全模型部署名称。
`endpoint`	路径	字符串	真实	Azure OpenAI 终结点。例如：`https://{YOUR_RESOURCE_NAME}.openai.azure.com`
`api-version`	查询	字符串	真实	要用于此操作的 API 版本。

请求正文

请求正文继承聊天补全 API 请求的相同架构。下表显示基于自有数据的 Azure OpenAI 的独有参数。

名称	类型	必需	说明
`data_sources`	DataSource[]	真实	基于自有数据的 Azure OpenAI 的配置条目。数组中必须只有一个元素。如果未提供 `data_sources`，该服务将直接使用聊天补全模型，并且不使用基于自有数据的 Azure OpenAI。指定 `data_sources` 参数时，将无法使用 `logprobs` 或 `top_logprobs` 参数。

响应正文

响应正文继承聊天补全 API 响应的相同架构。响应聊天消息具有一个 context 属性，该属性是为基于自有数据的 Azure OpenAI 添加的。

聊天消息

响应助手消息架构继承自聊天补全助手聊天消息，并使用属性 context 进行扩展。

名称	类型	必需	说明
`context`	上下文	假	表示处理请求时基于自有数据的 Azure OpenAI 执行的增量步骤，包括检索到文档。

上下文

名称	类型	必需	说明
`citations`	引文[]	假	数据源检索结果，用于在响应中生成助手消息。客户端可以从引文中呈现参考文献。
`intent`	字符串	假	从聊天历史记录检测到的意向。不再需要传递回上一个意向。忽略此属性。
`all_retrieved_documents`	检索到文档[]	假	所有检索到的文档。

引文

名称	类型	必需	说明
`content`	字符串	真实	引文的内容。
`title`	字符串	假	引文的标题。
`url`	字符串	假	引文的 URL。
`filepath`	字符串	假	引文的文件路径。
`chunk_id`	字符串	假	引文的区块 ID。

检索的文档

名称	类型	必需	说明
`search_queries`	字符串[]	真实	用于检索文档的搜索查询。
`data_source_index`	整数	真实	数据源的索引。
`original_search_score`	翻倍	真实	检索到的文档的原始搜索分数。
`rerank_score`	翻倍	假	检索到的文档的重新排名分数。
`filter_reason`	字符串	假	表示筛选文档的理由。如果文档未经过筛选，则此字段将保持未设置状态。如果文档按由 `score` 定义的原始搜索分数阈值进行筛选，则此字段将为 `strictness`。如果文档未按原始搜索分数阈值进行筛选，而是按重新排名分数和 `rerank` 进行筛选，则此字段将为 `top_n_documents`。

数据源

下面列出了支持的数据源。

示例

此示例演示如何传递对话历史记录，以便获得更好的结果。

先决条件：

配置从 Azure OpenAI 系统分配的托管标识到 Azure 搜索服务的角色分配。必需的角色：Search Index Data Reader、Search Service Contributor。
配置用户到 Azure OpenAI 资源的角色分配。必需的角色：Cognitive Services OpenAI User。
安装 Az CLI 并运行 az login。
定义以下环境变量：AzureOpenAIEndpoint、ChatCompletionsDeploymentName、SearchEndpoint、SearchIndex。

export AzureOpenAIEndpoint=https://example.openai.azure.com/
export ChatCompletionsDeploymentName=turbo
export SearchEndpoint=https://example.search.windows.net
export SearchIndex=example-index

Python 1.x
休息

安装最新的 pip 包 openai、azure-identity。

import os
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

endpoint = os.environ.get("AzureOpenAIEndpoint")
deployment = os.environ.get("ChatCompletionsDeploymentName")
search_endpoint = os.environ.get("SearchEndpoint")
search_index = os.environ.get("SearchIndex")

token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

client = AzureOpenAI(
    azure_endpoint=endpoint,
    azure_ad_token_provider=token_provider,
    api_version="2024-05-01-preview",
)

completion = client.chat.completions.create(
    model=deployment,
    messages=[
        {
            "role": "user",
            "content": "Who is DRI?",
        },
        {
            "role": "assistant",
            "content": "DRI stands for Directly Responsible Individual of a service. Which service are you asking about?"
        },
        {
            "role": "user",
            "content": "Opinion mining service"
        }
    ],
    extra_body={
        "data_sources": [
            {
                "type": "azure_search",
                "parameters": {
                    "endpoint": search_endpoint,
                    "index_name": search_index,
                    "authentication": {
                        "type": "system_assigned_managed_identity"
                    }
                }
            }
        ]
    }
)

print(completion.model_dump_json(indent=2))

# render the citations

content = completion.choices[0].message.content
context = completion.choices[0].message.context
for citation_index, citation in enumerate(context["citations"]):
    citation_reference = f"[doc{citation_index + 1}]"
    url = "https://example.com/?redirect=" + citation["url"] # replace with actual host and encode the URL
    filepath = citation["filepath"]
    title = citation["title"]
    snippet = citation["content"]
    chunk_id = citation["chunk_id"]
    replaced_html = f"<a href='{url}' title='{title}\n{snippet}''>(See from file {filepath}, Part {chunk_id})</a>"
    content = content.replace(citation_reference, replaced_html)
print(content)

az rest --method POST \
 --uri $AzureOpenAIEndpoint/openai/deployments/$ChatCompletionsDeploymentName/chat/completions?api-version=2024-05-01-preview \
 --resource https://cognitiveservices.azure.com/ \
 --body \
'
{
    "data_sources": [
        {
            "type": "azure_search",
            "parameters": {
                "endpoint": "'$SearchEndpoint'",
                "index_name": "'$SearchIndex'",
                "authentication": {
                    "type": "system_assigned_managed_identity"
                }
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Who is DRI?"
        },
        {
            "role": "assistant",
            "content": "DRI stands for Directly Responsible Individual of a service. Which service are you asking about?"
        },
        {
            "role": "user",
            "content": "Opinion mining service"
        }
    ]
}
'

通过