Azure OpenAI On Your Data API 參考

2025-07-02

本文提供適用於新 Azure OpenAI On Your Data API 的 Python 和 REST 參考文件。最新的 API 版本是 2024-05-01-previewSwagger 規格。

備註

從 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 規格。
2024-02-01 Swagger 規格。
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 On Your Data API 獨有的參數。

名稱	類型	為必填項目	說明
`data_sources`	數據源	對	Azure OpenAI On Your Data API 的組態項目。陣列中必須正好有一個元素。如果未提供 `data_sources`，服務會直接使用聊天完成模型，且不會使用 Azure OpenAI On Your Data API。當您指定 `data_sources` 參數時，將無法使用 `logprobs` 或 `top_logprobs` 參數。

回應主體

回應本文會繼承聊天完成 API 回應的相同結構描述。回應聊天訊息具有 context 屬性，這是針對 Azure OpenAI On Your Data API 新增的屬性。

聊天訊息

回應小幫手訊息結構描述繼承自聊天完成小幫手聊天訊息，並使用屬性 context 進行擴充。

名稱	類型	為必填項目	說明
`context`	背景	否	表示 Azure OpenAI On Your Data 在處理要求時所執行的累加步驟，包括擷取的文件。

上下文

名稱	類型	為必填項目	說明
`citations`	引文[]	否	資料來源擷取結果，用於在回應中產生小幫手訊息。用戶端可以從引文轉譯參考。
`intent`	字串	否	從聊天記錄偵測到的意圖。不再需要傳回先前的意圖。忽略這個屬性。
`all_retrieved_documents`	擷取的文件[]	否	所有擷取的文件。

引文

名稱	類型	為必填項目	說明
`content`	字串	對	引文的內容。
`title`	字串	否	引文的標題。
`url`	字串	否	引文的 URL。
`filepath`	字串	否	引文的檔案路徑。
`chunk_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"
        }
    ]
}
'