使用Custom Web API Skill调用Azure OpenAI嵌入模型遇input参数缺失问题

问题场景 #

尝试通过Azure认知搜索的Custom Web API Skill调用Azure OpenAI的text-embedding-3-small嵌入模型，使用以下技能集配置：

{
  "name": "skillset-name",
  "description": "",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
      "name": "Text Embedding",
      "description": "",
      "context": "/document",
      "uri": "https://my_endpoint/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-02-01&model=text-embedding-3-small&dimensions=512",
      "httpMethod": "POST",
      "timeout": "PT30S",
      "batchSize": 1000,
      "degreeOfParallelism": null,
      "inputs": [
        {
          "name": "input",
          "source": "/document/representacao_vetorial"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "vetor"
        }
      ],
      "httpHeaders": {
        "api-key": "api-key"
      },
      "authIdentity": null
    }
  ],
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.DefaultCognitiveServices",
    "description": null
  },
  "knowledgeStore": null,
  "indexProjections": null,
  "encryptionKey": null
}

运行索引器时收到以下错误：

Web Api response status: 'BadRequest', Web Api response details: '{
  "error": {
    "message": "'input' is a required property",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}'

问题原因 #

Azure OpenAI的Embeddings API要求请求体根节点必须包含input字段（支持单个字符串或字符串数组），但默认情况下，Custom Web API Skill会将输入参数包装在values数组的data子字段中，导致API无法识别到必填的input参数。

解决方案 #

添加webApiRequestBodyTemplate字段，自定义请求体格式，将批量输入的文本映射到API要求的结构。修正后的技能集配置如下：

{
  "name": "skillset-name",
  "description": "",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
      "name": "Text Embedding",
      "description": "",
      "context": "/document",
      "uri": "https://my_endpoint/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-02-01&model=text-embedding-3-small&dimensions=512",
      "httpMethod": "POST",
      "timeout": "PT30S",
      "batchSize": 1000,
      "degreeOfParallelism": null,
      "inputs": [
        {
          "name": "input",
          "source": "/document/representacao_vetorial"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "vetor"
        }
      ],
      "httpHeaders": {
        "api-key": "api-key"
      },
      "authIdentity": null,
      // 新增模板，适配Azure OpenAI的请求格式
      "webApiRequestBodyTemplate": "{'input': [for (value in $values) {value.data.input}]}"
    }
  ],
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.DefaultCognitiveServices",
    "description": null
  },
  "knowledgeStore": null,
  "indexProjections": null,
  "encryptionKey": null
}

关键说明 #

• webApiRequestBodyTemplate使用Jinja2模板语法，遍历$values数组（批量请求的每个条目），将每个条目的data.input收集为数组，赋值给根节点的input字段，完全匹配Azure OpenAI Embeddings API的请求格式。
• 若batchSize设为1（单条请求），模板可简化为{'input': '$values[0].data.input'}，但保持数组格式更兼容批量场景。

内容的提问来源于stack exchange，提问作者Vitor Alcântara Batista