Azure内置技能实现Blob文本分块嵌入并存储向量库遇问题求助

一、技能组合失败的修复方案 #

• 核对输入输出映射：拆分技能的输出字段必须正确关联到嵌入技能的输入。比如拆分技能输出/document/splitText，嵌入技能的输入要设为/document/splitText/*（用通配符*遍历所有分块），否则只会处理第一个分块，导致后续流程异常。
• 确认技能执行顺序：技能集里必须先定义拆分技能，再定义嵌入技能，Azure认知搜索严格按技能定义顺序执行，颠倒顺序会导致嵌入技能找不到分块数据。
• 匹配分块与嵌入的长度限制：嵌入技能对输入文本长度有上限（例如text-embedding-ada-002支持8191 tokens），调整拆分技能的maximumPageLength参数（建议设为5000字符左右，根据token换算），同时开启allowOverflowOnFinalPage，避免单个分块超限制触发嵌入失败。
• 查看索引器错误日志：在Azure认知搜索的索引器运行历史中提取具体错误信息，比如输入字段不存在、嵌入服务权限不足或调用超时，针对性修复问题。

二、分块唯一ID的创建方案 #

• 使用内置GenerateId技能生成唯一ID：在技能集中添加GenerateId技能，基于原文件标识和分块索引生成唯一ID，配置示例：

{
  "@odata.type": "#Microsoft.Skills.Util.GenerateIdSkill",
  "name": "SplitIdGenerator",
  "context": "/document/splitText/*",
  "inputs": [
    {
      "name": "seed",
      "source": "/document/metadata_storage_path"
    },
    {
      "name": "index",
      "source": "/document/splitText/*#index"
    }
  ],
  "outputs": [
    {
      "name": "id",
      "targetName": "splitId"
    }
  ]
}

该配置以文件存储路径为种子，结合分块的索引值，确保每个分块的ID唯一且可追溯。

• 映射ID到向量数据库主键：在索引器的字段映射中，将生成的splitId关联到向量数据库的主键字段，示例：

{
  "sourceFieldName": "/document/splitText/*/splitId",
  "targetFieldName": "id",
  "mappingFunction": {
    "name": "base64Encode"
  }
}

如果主键需要特定格式（如base64编码），可通过映射函数处理。

• 避免ID冲突：确保原文件的标识（如存储路径、文件名）全局唯一，结合分块索引后，能彻底避免分块ID重复导致的数据覆盖或入库失败。

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