项目级词库与检索、图谱及智能体协同
词库用于维护近义词、追加词和停止词。项目可以分别管理词库,再将其绑定到知识库或智能体;绑定前建议先用预览功能检查实际改写结果。词库规则不能替代完整的安全防护或内容审核。
功能概述与核心场景
在企业客服和技术支持场景中,用户常使用简称、俗称或故障码提问,而资料中可能使用标准术语。词库可以维护这些术语之间的关系,帮助团队在检索和智能体场景中统一管理。
核心概念与架构
流程示意,不是运行截图。
词库中的词条使用 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}/preview | lexicons.read,并具备相应词库读取权限 |
| 创建词库与词条、导入或修改 | POST /v1/lexicons、POST /v1/lexicons/{lexiconId}/entries、POST /v1/lexicons/{lexiconId}/import | lexicons.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/lexicons | agent-runtime.project 及相应项目、智能体和词库访问权限;写入需满足当前版本管理要求 |
创建与预览
在项目中进入知识库 → 词库,创建词库并填写名称和可选描述。
进入词库详情,在词条页添加近义词、追加词或停止词。
切换到预览页签,输入查询并提交。页面显示原始查询、改写结果、分词、停止词命中和映射结果。
将需要的词库绑定到知识库或智能体,并检查绑定启用状态和顺序。知识库的图谱索引是否使用词库,还取决于相应索引配置;变更后是否需要重建,按具体索引状态确认。
导入和导出
在词库详情的导入/导出页签,可以选择 JSON、CSV 或 XLSX 文件。控制台限制单个文件不超过 5 MiB;JSON 文件应为词条数组。导入前先选择模式并执行试运行,检查逐行结果。试运行无错误且有可导入词条后,确认应用;变更文件或模式后需要重新试运行。
merge:保留已有词条,跳过去重键相同的词条,再添加其余词条;不会合并已有词条的变体。overwrite:替换该词库现有词条集合,而非仅覆盖同名项。操作前先导出备份并检查试运行结果;现有词条超过 1,000 条时不能使用此方式覆盖。
导出可选择 JSON、CSV 或 XLSX。导入接口一次最多接收 1,000 条,详细错误以实际返回为准。
绑定到知识库与智能体
先读取目标知识库现有绑定,并确认保留哪些词库;更新绑定会替换整个绑定列表。
在请求体中设置顶层
enabled,并按需要提供bindings:每项包含lexiconId与priority。保存后重新读取绑定,再用相同查询检查结果。智能体工作台的绑定独立配置;在工作台检查选中词库和优先级。需要命中停止词后拦截时,可启用
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,正常用语命中停止词可能触发拦截。建议区分检索降噪和拦截用途,并用代表性的正常提问测试规则。
创建词库返回服务端错误怎么办? 保留请求时间和错误信息,联系管理员检查当前环境的词库结构与服务版本是否一致;不要反复提交或自行修改数据库结构。
预览命中停止词怎么办? 检查停止词是否覆盖了正常用户用语,再决定调整词条或绑定;拦截不是通用的提示注入防护。
为什么无法应用导入? 检查文件格式、试运行错误和可导入条数;文件或模式变更后重新试运行。
为什么绑定后结果没有变化? 检查绑定是否启用、词库是否有权读取及具体检索或索引配置,再用相同输入预览和测试。