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

数据源 - Azure AI 搜索

项目
09/20/2024

使用基于自有数据的 Azure OpenAI 时的 Azure AI 搜索的可配置选项。 API 版本 2024-02-01 支持此数据源。

名称	类型	必需	说明
`parameters`	Parameters	True	配置 Azure 认知搜索时要使用的参数。
`type`	string	True	必须是 `azure_search`。

参数

客户	类型	必需	说明
`endpoint`	字符串	True	要使用的 Azure 认知搜索资源的绝对终结点路径。
`index_name`	string	True	在引用的 Azure 认知搜索资源中使用的索引的名称。
`authentication`	ApiKeyAuthenticationOptions、SystemAssignedManagedIdentityAuthenticationOptions、UserAssignedManagedIdentityAuthenticationOptions、onYourDataAccessTokenAuthenticationOptions 之一	True	访问定义的数据源时要使用的身份验证方法。
`embedding_dependency`	DeploymentNameVectorizationSource、EndpointVectorizationSource 之一	False	矢量搜索的嵌入依赖项。当 `query_type` 是 `vector`、`vector_simple_hybrid` 或 `vector_semantic_hybrid` 时为必需项。
`fields_mapping`	FieldsMappingOptions	False	与搜索索引交互时要使用的自定义字段映射行为。
`filter`	string	False	搜索筛选器。
`in_scope`	boolean	False	是否应将查询限制为使用索引数据。默认值为 `True`。
`query_type`	QueryType	False	用于 Azure 认知搜索的查询类型。默认为 `simple`
`role_information`	string	False	为模型提供有关它应该如何运行以及在生成回复时应引用的任何上下文的说明。你可以描述助手的个性，告诉它如何设置回复的格式。
`semantic_configuration`	string	False	查询的语义配置。当 `query_type` 是 `semantic` 或 `vector_semantic_hybrid` 时为必需项。
`strictness`	integer	False	搜索相关性筛选的已配置严格性。严格度越高，精准率越高，但回复的召回率越低。默认值为 `3`。
`top_n_documents`	integer	False	为配置的查询提供的已配置最多文档数。默认值为 `5`。
`max_search_queries`	integer	False	对于一条用户消息，应将最大数量的重写查询发送到搜索提供程序。如果未指定，系统将决定要发送的查询数。
`allow_partial_result`	integer	False	如果指定为 true，系统将允许使用部分搜索结果，如果所有查询都失败，请求将失败。如果未指定或指定为 false，若任何搜索查询失败，则请求将失败。
`include_contexts`	array	False	输出上下文所包含的属性。如果未指定，默认值为 `citations` 和 `intent`。值可以是 `citations`、`intent`、`all_retrieved_documents`。

API 密钥验证选项

使用 API 密钥时，基于自有数据的 Azure OpenAI 的验证选项。

名称	类型	必需	说明
`key`	字符串	True	用于身份验证的 API 密钥。
`type`	string	True	必须是 `api_key`。

系统分配的托管标识验证选项

使用系统分配的托管标识时，基于自有数据的 Azure OpenAI 的验证选项。

名称	类型	必需	说明
`type`	字符串	True	必须是 `system_assigned_managed_identity`。

用户分配的托管标识验证选项

使用用户分配的托管标识时，基于自有数据的 Azure OpenAI 的验证选项。

名称	类型	必需	说明
`managed_identity_resource_id`	字符串	True	用于进行身份验证的用户分配托管标识的资源 ID。
`type`	string	True	必须是 `user_assigned_managed_identity`。

访问令牌验证选项

使用访问令牌时，基于自有数据的 Azure OpenAI 的验证选项。

名称	类型	必需	说明
`access_token`	字符串	True	要用于身份验证的访问令牌。
`type`	string	True	必须是 `access_token`。

部署名称矢量化源

应用矢量搜索时基于自有数据的 Azure OpenAI 使用的矢量化源的详细信息。此矢量化源基于同一 Azure OpenAI 资源中的内部嵌入模型部署名称。此矢量化可以在没有 Azure OpenAI API 密钥和 Azure OpenAI 公用网络访问的情况下使用矢量搜索。

名称	类型	必需	说明
`deployment_name`	字符串	True	同一 Azure OpenAI 资源中的嵌入模型部署名称。
`type`	string	True	必须是 `deployment_name`。
`dimensions`	integer	False	嵌入应有的维度数。仅在 `text-embedding-3` 及更高版本中受支持。

终结点矢量化源

应用矢量搜索时基于自有数据的 Azure OpenAI 使用的矢量化源的详细信息。此矢量化源基于 Azure OpenAI 嵌入 API 终结点。

名称	类型	必需	说明
`endpoint`	字符串	True	指定应从中检索嵌入的资源终结点 URL。其格式应为：`https://{YOUR_RESOURCE_NAME}.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings`。不允许 api-version 查询参数。
`authentication`	ApiKeyAuthenticationOptions	True	指定从指定终结点检索嵌入时要使用的验证选项。
`type`	string	True	必须是 `endpoint`。
`dimensions`	integer	False	嵌入应有的维度数。仅在 `text-embedding-3` 及更高版本中受支持。

字段映射选项

用于控制使用配置的 Azure 认知搜索资源时如何处理字段的可选设置。

名称	类型	必需	说明
`content_fields`	string[]	False	应被视为内容的索引字段的名称。
`vector_fields`	string[]	False	表示矢量数据的字段的名称。
`content_fields_separator`	string	False	内容字段应使用的分隔符模式。默认值为 `\n`。
`filepath_field`	string	False	要用作文件路径的索引字段的名称。
`title_field`	string	False	要用作标题的索引字段的名称。
`url_field`	string	False	要用作 URL 的索引字段的名称。

查询类型

在将其用作基于自有数据的 Azure OpenAI 时应执行的 Azure 认知搜索检索查询的类型。

枚举值	说明
`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、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
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?",
        }
    ]
}
'

通过