數據源 - Azure AI 搜尋

發行項
05/30/2024

在您的數據上使用 Azure OpenAI 時，Azure AI 搜尋的可設定選項。 API 版本 2024-02-01支援此資料來源。

名稱	類型	必要	描述
`parameters`	參數	True	設定 Azure 搜尋服務時要使用的參數。
`type`	字串	True	必須是 `azure_search`。

參數

姓名	類型	必要	描述
`endpoint`	string	True	要使用的 Azure 搜尋服務資源的絕對端點路徑。
`index_name`	字串	True	在參考的 Azure 搜尋服務資源中使用的索引名稱。
`authentication`	其中一個 ApiKeyAuthenticationOptions、SystemAssignedManagedIdentityAuthenticationOptions、UserAssignedManagedIdentityAuthenticationOptions 、onYourDataAccessTokenAuthenticationOptions	True	存取已定義數據源時要使用的驗證方法。
`embedding_dependency`	其中一個 DeploymentNameVectorizationSource、 EndpointVectorizationSource	False	向量搜尋的內嵌相依性。當為 `vector`、 `vector_simple_hybrid`或 `vector_semantic_hybrid`時`query_type`，則為必要項。
`fields_mapping`	FieldsMappingOptions	False	與搜尋索引互動時要使用的自定義欄位對應行為。
`filter`	字串	False	搜尋篩選條件。
`in_scope`	boolean	False	查詢是否應該限制為使用索引數據。預設值為 `True`。
`query_type`	QueryType	False	要與 Azure 搜尋服務搭配使用的查詢類型。預設為 `simple`
`role_information`	字串	False	提供模型關於其行為方式的指示，以及產生回應時應該參考的任何內容。您可以描述助理的個性，並告知其如何格式化回應。
`semantic_configuration`	字串	False	查詢的語意組態。當為 `semantic` 或 `vector_semantic_hybrid`時`query_type`為必要項。
`strictness`	整數	False	已設定的搜尋相關性篩選嚴格性。嚴格程度越高，精確度越高，但對答案的召回率較低。預設值為 `3`。
`top_n_documents`	整數	False	設定的檔數目已設定為已設定查詢的功能。預設值為 `5`。
`max_search_queries`	整數	False	重寫查詢的數目上限應該傳送給搜尋提供者，以取得一個使用者訊息。如果未指定，系統會決定要傳送的查詢數目。
`allow_partial_result`	整數	False	如果指定為 true，系統會允許使用部分搜尋結果，如果所有查詢都失敗，要求就會失敗。如果未指定或指定為 false，則如果任何搜尋查詢失敗，要求將會失敗。
`include_contexts`	陣列	False	輸出內容的包含屬性。如果未指定，則預設值為 `citations` 和 `intent`。值可以是 `citations`、`intent`、 `all_retrieved_documents`。

API 金鑰驗證選項

使用 API 金鑰時，Azure OpenAI On Your Data 的驗證選項。

名稱	類型	必要	描述
`key`	string	True	要用於驗證的 API 金鑰。
`type`	字串	True	必須是 `api_key`。

系統指派的受控識別驗證選項

使用系統指派的受控識別時，Azure OpenAI On Your Data 的驗證選項。

名稱	類型	必要	描述
`type`	string	True	必須是 `system_assigned_managed_identity`。

使用者指派的受控識別驗證選項

使用使用者指派的受控識別時，Azure OpenAI On Data 的驗證選項。

名稱	類型	必要	描述
`managed_identity_resource_id`	string	True	要用於驗證的使用者指派受控識別資源標識碼。
`type`	字串	True	必須是 `user_assigned_managed_identity`。

存取令牌驗證選項

使用存取令牌時，Azure OpenAI On Your Data 的驗證選項。

名稱	類型	必要	描述
`access_token`	string	True	要用於驗證的存取令牌。
`type`	字串	True	必須是 `access_token`。

部署名稱向量化來源

套用向量搜尋時，Azure OpenAI On Your Data 所使用的向量化來源詳細數據。此向量化來源是以相同 Azure OpenAI 資源中的內部內嵌模型部署名稱為基礎。此向量化來源可讓您在沒有 Azure OpenAI API 金鑰的情況下使用向量搜尋，而不需要 Azure OpenAI 公用網路存取。

名稱	類型	必要	描述
`deployment_name`	string	True	相同 Azure OpenAI 資源內的內嵌模型部署名稱。
`type`	字串	True	必須是 `deployment_name`。
`dimensions`	整數	False	內嵌應具有的維度數目。僅支援 `text-embedding-3` 和更新版本的模型。

端點向量化來源

套用向量搜尋時，Azure OpenAI On Your Data 所使用的向量化來源詳細數據。此向量化來源是以 Azure OpenAI 內嵌 API 端點為基礎。

名稱	類型	必要	描述
`endpoint`	string	True	指定應該從中擷取內嵌的資源端點 URL。 `https://{YOUR_RESOURCE_NAME}.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings`格式應為。不允許 API 版本查詢參數。
`authentication`	ApiKeyAuthenticationOptions	True	指定從指定端點擷取內嵌時要使用的驗證選項。
`type`	字串	True	必須是 `endpoint`。
`dimensions`	整數	False	內嵌應具有的維度數目。僅支援 `text-embedding-3` 和更新版本的模型。

欄位對應選項

選擇性設定，可控制使用已設定的 Azure 搜尋服務資源時，字段的處理方式。

名稱	類型	必要	描述
`content_fields`	string[]	False	應視為內容的索引欄位名稱。
`vector_fields`	string[]	False	代表向量數據的功能變數名稱。
`content_fields_separator`	字串	False	內容欄位應該使用的分隔符模式。預設值為 `\n`。
`filepath_field`	字串	False	要當做檔案路徑使用的索引字段名稱。
`title_field`	字串	False	要當做標題使用的索引字段名稱。
`url_field`	字串	False	要當做 URL 使用的索引欄位名稱。

查詢類型

Azure 搜尋服務擷取查詢的類型，應該在做為 Azure OpenAI On Your Data 時執行。

列舉值	描述
`simple`	表示預設的簡單查詢剖析器。
`semantic`	表示進階語意模型化的語意查詢剖析器。
`vector`	表示計算數據的向量搜尋。
`vector_simple_hybrid`	表示簡單查詢策略與向量數據的組合。
`vector_semantic_hybrid`	表示語意搜尋和向量數據查詢的組合。

範例

先決條件：

設定從 Azure OpenAI 系統指派受控識別給 Azure 搜尋服務的角色指派。必要角色： Search Index Data Reader、 Search Service Contributor。
設定從使用者到 Azure OpenAI 資源的角色指派。必要角色： Cognitive Services OpenAI User。
安裝 Az CLI，然後執行 az login。
定義下列環境變數：AzureOpenAIEndpoint、、、SearchEndpoint。SearchIndexChatCompletionsDeploymentName

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

Python 1.x
REST

安裝最新的 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-02-01",
)

completion = client.chat.completions.create(
    model=deployment,
    messages=[
        {
            "role": "user",
            "content": "Who is DRI?",
        },
    ],
    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))

az rest --method POST \
 --uri $AzureOpenAIEndpoint/openai/deployments/$ChatCompletionsDeploymentName/chat/completions?api-version=2024-02-01 \
 --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?",
        }
    ]
}
'

共用方式為