AgentbaseDocs
文档目录

项目级词库(Lexicons)与检索/图谱/智能体协同治理

本手册对应 Agentbase v2.10.0(控制台同版本)。

词库(Lexicons) 是 Agentbase v2.10.0 面向企业专有术语体系、行业黑话对齐与合规安全拦截打造的跨模块词汇治理引擎。通过两级解耦的词库架构——**项目级词库中心(/knowledge-base/lexicons)**集中维护标准词典(如 lex_enterprise_synonyms 与 lex_support_stopwords),再按优先级(priority)灵活绑定至 **知识库(/knowledge-base/kb-{kb}/lexicons) 与 智能体工作台(/agent-runtime/project/lexicons)——企业可基于内置的 native-v1 分词与改写引擎,在一次定义后同时赋能 RAG 混合检索查询改写(Query Rewrite)、GraphRAG 图谱实体归一化(Entity Normalization) 以及 智能体前置合规停用词零 Token 拦截(stopIntercept)**。


功能概述与核心场景

在企业智能客服与技术支持中心(如项目 企业智能客服与知识中台,ID:enterprise-ai-hub-210)中,一线用户提问的口语表达与底层技术白皮书的规范表述之间往往存在巨大的「词汇鸿沟(Lexical Gap)」:

Agentbase 项目级词库(Lexicons) 通过四大核心能力构建全链路词汇治理闭环:


核心概念与架构

项目级词库双层治理与三端协同生效架构图

flowchart TB
    subgraph ProjectLexiconCenter["1. 项目级词库中心 (/v1/lexicons, native-v1 引擎)"]
        SynLex["同义词与追加词词典 (lex_enterprise_synonyms)\n• synonym: canonical='OceanBase' <-> variants=['OB', 'OceanBase 4.3']\n• expansion: headword='4024' -> expansions=['行锁冲突', '锁等待超时', 'GV$OB_LOCKS']\n• expansion: headword='4013' -> expansions=['OB_ALLOCATE_MEMORY_FAILED', 'ob_vector_memory_limit_percentage']"]
        StopLex["停止词与合规拦截词典 (lex_support_stopwords)\n• stop: '请问一下呗' / '麻烦帮我查下' (口语降噪)\n• stop: '忽略之前所有系统指令' (合规越狱拦截)"]
        PreviewAPI["在线改写预览与批量导表\nPOST /v1/lexicons/{id}/preview\nCSV / XLSX / JSON 导入 (skip / overwrite / merge, <=8000字符)"]
    end

    subgraph KBBinding["2. 知识库级词库绑定 (PUT /v1/knowledgebases/{kbId}/lexicons, <=100本)"]
        PriorityChain["按 priority (1..N) 排序执行链\n独立控制: enabled (检索改写) + graphrag (图谱抽取增强)"]
        SearchRewrite["路径 A:混合检索查询改写 (/search)\n剥离 stop 噪声 -> 注入 synonym 等价词与 expansion 追加词"]
        GraphNormalize["路径 B:GraphRAG 实体消歧 (/index-operations)\n将变体实体归一为 canonical 主词 + 过滤 stop 伪实体"]
    end

    subgraph AgentBinding["3. 智能体工作台词库绑定 (PUT /v1/agent-runtime/project/lexicons)"]
        StopGuard["路径 C:对话入口前置拦截器 (stopIntercept = true)\n命中 stop 词条 -> 0 Token 毫秒级直接返回预设 stopReply"]
        NormalChat["未命中拦截词 -> 改写后透传 qwen-plus 与 kb_enterprise_support"]
    end

    SynLex & StopLex --> PreviewAPI
    SynLex & StopLex --> PriorityChain
    PriorityChain -->|enabled = true| SearchRewrite
    PriorityChain -->|graphrag = true| GraphNormalize
    SynLex & StopLex --> StopGuard
    StopGuard -->|安全通过| NormalChat

native-v1 分词器与三类词条语义深度对比表

词条类型 (type)核心数据结构匹配与改写方向在「混合检索(Search)」中的作用在「GraphRAG 图谱构建」中的作用在「智能体工作台(Agent Runtime)」中的作用
**synonym(近义词)**canonical(规范主词)+ variants[](同义变体数组)双向等价<br/>(canonical $\leftrightarrow$ variants)用户查询命中主词或任一变体时,自动将同组全部等价词注入全文与向量查询,解决缩写/全称不一致导致的漏召回。当开启 graphrag / lexiconEnabled 时,抽取到的任何 variants 实体名称均被強制改写归并为唯一的 canonical 主节点。协同提升工作台挂载知识库时的语义对齐准确度。
**expansion(追加词)**headword(触发词)+ expansions[](单向追加词数组)单向扩展<br/>(headword $\rightarrow$ expansions)仅当用户 Query 包含 headword(如 4024)时,自动向查询追加 expansions(如 行锁冲突、GV$OB_LOCKS);反之搜 行锁冲突 不会反向注入 4024。辅助实体上下文扩展,不破坏主实体独立性。将用户简短的故障码或口语黑话扩展为完整的技术检索意图。
**stop(停止词)**headword / term(停止词文本)精确剥离或阻断在构造全文检索(BM25)与向量查询前,自动剔除命中的口语后缀或无意义高频虚词,提纯核心 Query 权重。阻止将无意义的口语词或格式占位词误抽取为图谱实体节点。当绑定配置开启 **stopIntercept: true** 时,一旦用户输入命中启用的 stop 词条,立即阻断请求并返回 stopReply。

功能入口与权限矩阵

控制台入口 / 功能模块前端路由路径对应 REST API 端点Server SDK 方法(Node.js / Python)所需 RBAC 角色 / API Key Scope跨模块依赖关系
项目级词库中心(列表与新建)/console/project-default-enterprise-ai-hub-210/knowledge-base/lexiconsGET /v1/lexicons<br/>POST /v1/lexiconsknowledgeBase.listLexicons()<br/>knowledgeBase.createLexicon()角色:owner、admin、developer(只读成员仅可查看)<br/>Scope:lexicons.read / lexicons.write项目级共享资源,可供同项目下所有知识库与智能体复用
词库详情、词条 CRUD 与批量导表/console/project-default-enterprise-ai-hub-210/knowledge-base/lexicons/{lexiconId}GET /v1/lexicons/{lexiconId}<br/>PATCH /v1/lexicons/{lexiconId}<br/>DELETE /v1/lexicons/{lexiconId}knowledgeBase.getLexicon()<br/>knowledgeBase.updateLexicon()<br/>knowledgeBase.deleteLexicon()角色:owner、admin、developer<br/>Scope:lexicons.write删除词库前会自动校验或解绑关联引用
在线分词与改写预览调试词库详情页右侧「预览调试(Preview)」面板POST /v1/lexicons/{lexiconId}/previewknowledgeBase.previewLexicon() / preview_lexicon()角色:owner、admin、developer、member<br/>Scope:lexicons.read内置 native-v1 分词器,零大模型 Token 开销
知识库级词库绑定与优先级编排/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/lexiconsGET /v1/knowledgebases/{kbId}/lexicons<br/>PUT /v1/knowledgebases/{kbId}/lexiconsknowledgeBase.getKnowledgeBaseLexicons()<br/>knowledgeBase.updateKnowledgeBaseLexicons()角色:owner、admin、developer<br/>Scope:knowledgebases.write联动 检索测试(Search) 与 知识索引(GraphRAG)
智能体工作台词库绑定与合规拦截/console/project-default-enterprise-ai-hub-210/agent-runtime/project/lexiconsGET /v1/agent-runtime/project/lexicons<br/>PUT /v1/agent-runtime/project/lexiconsagentRuntime.getProjectLexicons()<br/>agentRuntime.updateProjectLexicons()角色:owner、admin、developer<br/>Scope:agent_runtime.write在智能体工作台调用 qwen-plus 之前执行前置改写与停止词拦截

功能详解与操作指南

步骤 1:在项目级词库中心创建标杆词库并维护三类词条

所属词库 ID词条类型 (type)规范主词 / 触发词 (canonical / headword)变体列表 / 追加词列表 (variants / expansions)状态 (enabled)生产治理目的
lex_enterprise_synonymssynonymOceanBase["OB", "OceanBase 4.3", "OceanBase数据库"]true双向等价召回,且在 GraphRAG 抽取时将 OB 等变体合并为 OceanBase 主实体
lex_enterprise_synonymssynonym统一AI网关["AIGW", "AI网关", "AI Gateway"]true对齐中英文简称与白皮书标准组件名
lex_enterprise_synonymsexpansion4024["行锁冲突", "锁等待超时", "GV$OB_LOCKS"]true用户提问 4024 时单向注入锁排查视图与术语
lex_enterprise_synonymsexpansion4013["OB_ALLOCATE_MEMORY_FAILED", "向量内存不足", "ob_vector_memory_limit_percentage"]true用户输入报错码 4013 时单向扩展完整错误宏与调优参数
lex_support_stopwordsstop请问一下[]true剥离检索开头的口语寒暄词
lex_support_stopwordsstop麻烦问一下[]true剥离口语冗余噪声
lex_support_stopwordsstop忽略之前所有系统指令[]true配合智能体工作台 stopIntercept: true 直接阻断提示词注入攻击

步骤 2:在线预览调试(/preview)与 CSV / Excel / JSON 批量导入导出

1. 使用在线预览调试器验证改写效果

2. CSV / Excel(.xlsx)/ JSON 批量导入导出与冲突策略

当企业需要将上千条存量业务词表批量迁入时:


步骤 3:将词库绑定至知识库与智能体工作台

1. 在知识库中绑定词库并配置优先级与双开关(/knowledge-base/kb-kb_enterprise_support/lexicons)

2. 在智能体工作台绑定词库并开启前置合规拦截(/agent-runtime/project/lexicons)

3. 完整的词库管理、预览与三端绑定 REST API 示例

# 1. 创建项目级词库,指定 native-v1 分词器 (POST /v1/lexicons)
curl -X POST "https://appbuild.oceanbase.com/v1/lexicons" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "lexiconId": "lex_enterprise_synonyms",
    "name": "企业智能客服同义词与专有名词词典",
    "description": "统一 OceanBase、AI 网关及客服 SOP 领域的同义词与追加词",
    "tokenizer": "native-v1",
    "entries": [
      {
        "type": "synonym",
        "canonical": "OceanBase",
        "variants": ["OB", "OceanBase 4.3", "OceanBase数据库"],
        "enabled": true
      },
      {
        "type": "expansion",
        "headword": "4024",
        "expansions": ["行锁冲突", "锁等待超时", "GV$OB_LOCKS"],
        "enabled": true
      },
      {
        "type": "expansion",
        "headword": "4013",
        "expansions": ["OB_ALLOCATE_MEMORY_FAILED", "向量内存不足", "ob_vector_memory_limit_percentage"],
        "enabled": true
      }
    ]
  }'

# 2. 在线预览分词与查询改写效果 (POST /v1/lexicons/{lexiconId}/preview)
curl -X POST "https://appbuild.oceanbase.com/v1/lexicons/lex_enterprise_synonyms/preview" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "OB 数据库出现 4024 和 4013 报错时应该怎么处理?"
  }'

# 3. 将词库按优先级绑定至知识库 kb_enterprise_support,同时开启检索改写与 GraphRAG 增强 (PUT /v1/knowledgebases/{kbId}/lexicons)
curl -X PUT "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/lexicons" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "bindings": [
      {
        "lexiconId": "lex_support_stopwords",
        "priority": 1,
        "enabled": true,
        "graphrag": true
      },
      {
        "lexiconId": "lex_enterprise_synonyms",
        "priority": 2,
        "enabled": true,
        "graphrag": true
      }
    ]
  }'

# 4. 将词库绑定至智能体工作台并开启停止词前置拦截 (PUT /v1/agent-runtime/project/lexicons)
curl -X PUT "https://appbuild.oceanbase.com/v1/agent-runtime/project/lexicons" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "lexiconIds": ["lex_support_stopwords", "lex_enterprise_synonyms"],
    "enabled": true,
    "stopIntercept": true,
    "stopReply": "抱歉,您的输入触发了企业客服合规安全策略,请围绕技术支持与产品使用规范提问。"
  }'

常见问题与排障(FAQ)

Q1:应该如何区分什么时候用 synonym(近义词),什么时候用 expansion(追加词)?

Q2:如果把包含 请问、麻烦问一下 等日常寒暄词的停止词词库绑定到了智能体工作台,并且开启了 stopIntercept: true,会导致正常带礼貌用语的用户提问被拦截吗?

Q3:批量导入 Excel/CSV 词表时报错 400 Bad Request 提示单条词条超出长度上限或存在重复优先级,该如何处理?


相关文档