Azure OpenAI自定义数据索引在Python机器人中的配置问题

一、修正自定义字段映射逻辑 #

手动映射后无法识别数据，核心是字段映射规则没匹配Azure OpenAI On Your Data的要求：

• 必须确保索引里的content字段是Edm.String类型且开启Searchable=true，这是检索的核心字段。手动映射时要把JSON数组中存储详细内容的字段（比如站点信息、风险说明）对应到这个字段，别把Site_ID、question这类元数据字段当成content。
• Site_ID、question转成string后，要在索引里设为Edm.String类型，同时开启filterable=true，映射时归类为元数据字段，用于过滤而非检索内容。
• 用Python客户端创建索引的示例代码：

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    SearchIndex,
    SimpleField,
    SearchableField,
    FieldMapping
)

# 初始化索引客户端
index_client = SearchIndexClient(endpoint=SEARCH_ENDPOINT, credential=SEARCH_KEY)
# 定义索引字段
fields = [
    SearchableField(name="content", type="Edm.String", searchable=True, retrievable=True),
    SimpleField(name="Site_ID", type="Edm.String", filterable=True, retrievable=True),
    SimpleField(name="question", type="Edm.String", filterable=True, retrievable=True),
    # 其他业务字段按需添加
]
# 创建/更新索引
index = SearchIndex(name=INDEX_NAME, fields=fields)
index_client.create_or_update_index(index)

# 数据导入时的字段映射（如果JSON字段名和索引字段名不一致）
field_mappings = [
    FieldMapping(source_field_name="site_details", target_field_name="content"),
    FieldMapping(source_field_name="site_id", target_field_name="Site_ID"),
    FieldMapping(source_field_name="q_id", target_field_name="question")
]

二、修复Python机器人的On Your Data调用逻辑 #

官方示例代码可能没明确指定字段映射，调用时必须在azure_extensions_options里配置清楚：

from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint=AZURE_OPENAI_ENDPOINT,
    api_key=AZURE_OPENAI_KEY,
    api_version=API_VERSION
)

response = client.chat.completions.create(
    model=DEPLOYMENT_NAME,
    messages=[{"role": "user", "content": "查Site_ID为123的站点风险情况"}],
    azure_extensions_options={
        "extensions": [
            {
                "type": "azure_search",
                "parameters": {
                    "endpoint": SEARCH_ENDPOINT,
                    "key": SEARCH_KEY,
                    "index_name": INDEX_NAME,
                    "field_mapping_options": {
                        "content_fields": ["content"],  # 对应索引里的核心检索字段
                        "metadata_fields": ["Site_ID", "question"],  # 元数据字段用于过滤
                        "title_field": "site_name"  # 可选，对应站点名称类字段
                    },
                    "query_type": "semantic",
                    "top_n_documents": 5
                }
            }
        ]
    }
)

三、数据导入前的格式校验 #

把4个txt合并成JSON数组时，要确保格式符合检索要求：

• 每个JSON对象的字段名和索引字段名完全匹配，或者通过字段映射对应，别用嵌套过深的结构（Azure认知搜索对嵌套字段检索支持有限）。
• 把站点信息、风险指标、缓解措施等需要检索的内容，合并成一段文本存入content字段，别拆分到多个字段里。
• 单条数据示例：

{
    "content": "Site_ID: 123，站点名称：XX水库，风险等级：3级，缓解措施：加固堤坝、增设预警系统...",
    "Site_ID": "123",
    "question": "1",
    "risk_level": "3"
}

四、Playground手动映射的验证步骤 #

在Playground里手动映射时，别选错字段：

• 勾选「启用字段映射」后，Content field必须选索引里的content字段（可搜索的核心字段），不能选Site_ID这类元数据字段。
• Metadata fields选Site_ID、question这类需要过滤的字段，测试查询时带上元数据条件，比如问「Site_ID为123的站点有什么风险？」，验证是否能命中数据。

内容的提问来源于stack exchange，提问作者ChrisGila