必须在向量化前启用同义词映射功能，按标准格式配置或上传同义词表，通过测试查询验证归一效果，确保语义相近但字面不同的词能准确映射并提升召回率。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在火山引擎知识库中实现精准知识查询，必须解决用户输入词与知识文档中表述不一致的问题，比如“下单”和“购买”、“退款”和“退钱”这类语义相近但字面不同的表达，否则检索结果会大量遗漏关键内容。
启用内置同义词映射功能
进入「知识库管理」→「设置」→「语义增强」，开启【同义词映射】开关。
这一步必须在知识库完成向量化前配置，否则已入库的向量不会自动重算，后续新增文档才生效。
点击「编辑同义词表」，按「标准词｜变体词1,变体词2」格式逐行填写，例如：下单｜购买,提交订单,确认支付。
保存后系统自动编译为语义归一化规则，查询时将用户输入的变体词实时映射到标准词再进行向量检索。
手动上传自定义同义词词典
方法一：使用CSV模板上传
下载官方提供的同义词CSV模板，第一列为标准词（必须唯一），第二列为逗号分隔的变体词（支持中文、英文、中英文混合）。
注意：同一标准词下最多允许30个变体词，超出部分会被截断且不报错，需自行校验行数。
上传后点击「立即生效」，系统将在30秒内完成热加载，无需重启服务或重新构建索引。
方法二：通过API批量注入
调用/v1/kb/synonym/batch_upsert接口，以JSON数组形式提交同义词组，每组包含canonical_term和variants字段。
该方式适合与CRM、客服工单系统打通，实现业务术语变更后自动同步至知识库语义层。
验证同义词是否生效
第一步：在知识库「测试查询」面板输入一个变体词，如“退钱”；
第二步：勾选「查看语义改写过程」；
第三步：观察返回日志中是否出现→ 归一为：退款字样；
第四步：对比关闭同义词开关时的召回结果，确认命中了原本未匹配到的含“退款”关键词的文档段落。
如果未看到归一记录，说明该词未被词典收录，或存在全角/半角空格、隐藏字符等导致匹配失败——此时需复制原始输入到十六进制编辑器中排查。
