Docs
文档目录

项目级词库与检索、图谱及智能体协同

词库用于维护近义词、追加词和停止词。项目可以分别管理词库,再将其绑定到知识库或智能体;绑定前建议先用预览功能检查实际改写结果。词库规则不能替代完整的安全防护或内容审核。

功能概述与核心场景

在企业客服和技术支持场景中,用户常使用简称、俗称或故障码提问,而资料中可能使用标准术语。词库可以维护这些术语之间的关系,帮助团队在检索和智能体场景中统一管理。

核心概念与架构

词库维护与绑定:流程示意,不是运行截图

流程示意,不是运行截图。

查看流程图大图

词库中的词条使用 entryType、terms 和可选的 expansions:

词条类型用途示例
synonym将一组词作为近义词处理,改写方式由词库的 synonymRewriteMode 决定。terms: ["OceanBase", "OB"]
expansion命中 terms 中的词时追加关联词。terms: ["4024"],expansions: ["行锁冲突"]
stop标记停止词命中;智能体绑定可以配置命中后的拦截行为。terms: ["禁止词示例"]

terms 和 expansions 各最多 100 项,每项是非空 UTF-8 字符串,最多 256 个字符。expansion 必须提供非空 expansions;其他类型不能提供追加词。实际匹配与改写结果以预览为准。

功能入口与操作指南

操作接口所需权限与条件
查看词库、词条与预览GET /v1/lexicons、GET /v1/lexicons/{lexiconId}/entries、POST /v1/lexicons/{lexiconId}/previewlexicons.read,并具备相应词库读取权限
创建词库与词条、导入或修改POST /v1/lexicons、POST /v1/lexicons/{lexiconId}/entries、POST /v1/lexicons/{lexiconId}/importlexicons.write,并具备目标资源的写入权限
知识库词库绑定GET /v1/knowledgebases/{knowledgeBaseId}/lexicons、PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons分别需要 lexicons.read、lexicons.write,以及知识库和所选词库的相应资源权限
智能体工作台绑定GET /v1/agent-runtime/project/lexicons、PUT /v1/agent-runtime/project/lexiconsagent-runtime.project 及相应项目、智能体和词库访问权限;写入需满足当前版本管理要求

创建与预览

  1. 在项目中进入知识库 → 词库,创建词库并填写名称和可选描述。

  2. 进入词库详情,在词条页添加近义词、追加词或停止词。

  3. 切换到预览页签,输入查询并提交。页面显示原始查询、改写结果、分词、停止词命中和映射结果。

  4. 将需要的词库绑定到知识库或智能体,并检查绑定启用状态和顺序。知识库的图谱索引是否使用词库,还取决于相应索引配置;变更后是否需要重建,按具体索引状态确认。

导入和导出

在词库详情的导入/导出页签,可以选择 JSON、CSV 或 XLSX 文件。控制台限制单个文件不超过 5 MiB;JSON 文件应为词条数组。导入前先选择模式并执行试运行,检查逐行结果。试运行无错误且有可导入词条后,确认应用;变更文件或模式后需要重新试运行。

导出可选择 JSON、CSV 或 XLSX。导入接口一次最多接收 1,000 条,详细错误以实际返回为准。

绑定到知识库与智能体

  1. 先读取目标知识库现有绑定,并确认保留哪些词库;更新绑定会替换整个绑定列表。

  2. 在请求体中设置顶层 enabled,并按需要提供 bindings:每项包含 lexiconId 与 priority。保存后重新读取绑定,再用相同查询检查结果。

  3. 智能体工作台的绑定独立配置;在工作台检查选中词库和优先级。需要命中停止词后拦截时,可启用 stopIntercept 并配置 stopReply;关闭拦截不代表会剥离停止词。词库规则不能替代内容审核。

例如,绑定一个词库的请求体如下;如果需要保留已有绑定,应将它们一并列入:

{"enabled": true, "bindings": [{"lexiconId": "support_terms", "priority": 1}]}

通过 API 管理词库

以下示例假设 APPBASE_ENDPOINT 以 /v1 结尾,使用有相应词库权限的项目 API Key。标识和内容均为示例。

将 APPBASE_ENDPOINT 设置为目标环境的 API 地址(包含 /v1),确认项目和凭据属于该环境。请按顺序单独执行各步骤,并确认上一步结果。

创建词库

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/lexicons" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H 'Content-Type: application/json' \
    -d '{"lexiconId":"support_terms","name":"Support terms"}'
)

单独创建近义词词条

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/lexicons/support_terms/entries" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H 'Content-Type: application/json' \
    -d '{"entryType":"synonym","terms":["OceanBase","OB"]}'
)

预览查询改写

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/lexicons/support_terms/preview" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H 'Content-Type: application/json' \
    -d '{"query":"How do I use OB?"}'
)

绑定知识库时,PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons 的请求体使用顶层 enabled 和 bindings 数组;每项包含 lexiconId 与 priority。该操作会替换绑定列表,请先读取并保留仍需要的绑定。智能体绑定另有 stopIntercept 和 stopReply 配置;具体权限与入口以当前项目和智能体版本为准。

常见问题与排障

什么时候用 synonym,什么时候用 expansion? 对表示相同实体的词,如 OB 和 OceanBase,可以使用近义词;对于希望从故障码追加排查术语的场景,可以使用追加词。近义词的具体改写方式取决于词库配置,应通过预览验证。

停止词会拦截正常提问吗? 如果智能体绑定启用了 stopIntercept,正常用语命中停止词可能触发拦截。建议区分检索降噪和拦截用途,并用代表性的正常提问测试规则。

相关文档