AgentbaseDocs
文档目录

智能体模型、提示词、上下文精简与词库拦截配置

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

在智能体工作台(Agent Runtime)中,**运行配置(Config) 与 项目级词库绑定(Lexicon Bindings)** 共同决定了智能体的推理大脑、角色边界、单次任务成本上限以及对话入口的合规安全水位。通过在项目 企业智能客服与知识中台(enterprise-ai-hub-210)中精细编排主对话模型(如 qwen-plus)、采样参数、系统提示词、上下文窗口预算、自动上下文精简(Context Compaction) 以及 **停用词前置拦截(stopIntercept)**,企业可以在保障长对话连贯性的同时,彻底杜绝 Token 预算失控与恶意越狱提问穿透。


功能概述

在长周期、高并发的企业智能体运营中,配置管理往往面临三大工程挑战:一是多人同时在控制台调优参数容易互相覆盖,或误以为修改配置能中途改变正在执行的任务;二是多轮排障对话极易撑爆模型上下文窗口(Context Window),导致后续轮次直接报 Token 超限失败;三是用户的口语黑话(如 OB、4024)降低检索命中率,而违规词或越狱指令若直接送入大模型则白白消耗推理算力。

Agent Runtime 配置中心针对上述痛点提供了四大核心治理机制:


核心概念与架构

对话入口词库拦截、上下文预算计算与自动精简流水线

flowchart TB
    subgraph InputStage["1. 对话入口与前置词库拦截 (/v1/agent-runtime/project/lexicons)"]
        UserMsg["用户提交消息 (POST /runs)\nuser_message + thread_id + userId"]
        LexCheck{"词库引擎 (native-v1)\nenabled = true ?"}
        StopHit{"命中 stop 词条 且\nstopIntercept = true ?"}
        ShortCircuit["毫秒级短路拦截 (0 LLM Token)\n直接以 stopReply 作为回复结束本次 Run"]
        TermRewrite["同义词 (synonym) 与追加词 (expansion) 增强\n赋能后续知识库检索语义对齐"]
    end

    subgraph BudgetStage["2. 上下文窗口预算核算 (Config Snapshot)"]
        CalcBudget["计算可用输入预算:\nAvailable_Input = context_window_tokens (65536)\n- reserved_output_tokens (4096)\n- (system_prompt + 工具 Schema + Memory/PowerContext 召回)"]
        CheckHistory{"历史消息 + 本轮近期尾部\n是否超出精简阈值?"}
    end

    subgraph CompactionStage["3. 自动上下文精简 (Context Compaction)"]
        StartEvt["发出 SSE 事件 & 记录审计:\nCONTEXT_COMPACTION_STARTED"]
        TailCheck{"近期新鲜尾部 (Fresh Tail)\n本身是否已超出可用预算?"}
        Summarize["调用模型 (purpose=CONTEXT_COMPACTION)\n将早期历史消息压缩为结构化摘要 + 保留 Fresh Tail"]
        CompSuccess["记录 CONTEXT_COMPACTION_COMPLETED\n更新后续模型输入上下文 (不删除原始历史消息)"]
        CompFail["精简失败 (CONTEXT_COMPACTION_FAILED)\n错误码: CONTEXT_FRESH_TAIL_TOO_LARGE 或 CONTEXT_BUDGET_EXCEEDED"]
    end

    subgraph ReActLoop["4. 受控 ReAct 推理执行循环"]
        StepGuard["双重运行边界守卫:\n当前步数 <= max_steps (16) 且 累计耗时 <= max_duration_ms (180000ms)"]
        ModelCall["调用主对话模型 (qwen-plus, purpose=AGENT_RESPONSE)\ntemperature=0.3, top_p=0.9"]
    end

    UserMsg --> LexCheck
    LexCheck -- "否" --> CalcBudget
    LexCheck -- "是" --> StopHit
    StopHit -- "是 (命中受限词)" --> ShortCircuit
    StopHit -- "否" --> TermRewrite --> CalcBudget
    CalcBudget --> CheckHistory
    CheckHistory -- "未超阈值" --> StepGuard
    CheckHistory -- "达到精简阈值" --> StartEvt --> TailCheck
    TailCheck -- "是 (尾部过大无法精简)" --> CompFail
    TailCheck -- "否" --> Summarize --> CompSuccess --> StepGuard
    StepGuard --> ModelCall

运行配置(Config)全量字段规范与生产建议表

通过 GET /v1/agent-runtime/project/config 读取或 PATCH /v1/agent-runtime/project/config 更新项目运行配置时,各字段的类型、约束与生产标杆值如下:

字段名称类型必填 / 可空规则生产标杆值(enterprise-ai-hub-210)语义说明与工程边界约束
model_idstring首次保存必填"qwen-plus"必须为 GET /models 返回列表中具备 chat 能力的模型 ID。未配置时为 null,不能发起 Run。
model_parameters`object \null`首次保存必填{"temperature": 0.3, "top_p": 0.9}仅支持 temperature(0~1)与 top_p(0~1)。**注意:PATCH 时按整个对象替换而非逐键合并**;传入 {} 或 null 将清除显式采样参数。
system_prompt`string \null`可选(可为 null)"你是 Agentbase 企业智能客服与技术支持专家..."定义智能体角色、回答风格与引用规范。注意:系统提示词不能替代服务端权限控制;若需 JSON 格式回答需在此约定并在应用层校验。
context_window_tokensinteger首次保存必填(> 0)65536(或 32768)本次配置采用的模型上下文总窗口 Token 数,应小于等于所选物理模型(如 qwen-plus)支持的真实最大窗口。
reserved_output_tokensinteger首次保存必填4096(或 8192)为单次模型生成预留的输出 Token 预算,必须满足 0 < reserved_output_tokens < context_window_tokens。
max_stepsinteger首次保存必填(> 0)16(常见范围 8~64)单次 Run 允许的最大 ReAct 模型推理步数(不能超过实例部署上限,默认上限 64),防止工具调用无限循环。
max_duration_msinteger首次保存必填(> 0)180000(常见 120000~600000)单次 Run 的最长端到端执行毫秒数(如 180000 即 3 分钟,部署上限通常为 600000 即 10 分钟),超时将终止任务并标记 RUN_DEADLINE_EXCEEDED。
knowledge_search_enabledboolean首次保存必填true是否允许智能体调用内置 knowledge_retrieve 工具检索项目知识库。
knowledge_base_ids`string[] \null`开启知识检索时必填["kb_enterprise_support"]最多绑定 100 个不重复的同项目知识库 ID。新开启 knowledge_search_enabled: true 时不能为空数组;关闭检索时可保留已选列表以便下次一键恢复。
memory_enabledboolean首次保存必填true(与 powercontext_enabled 互斥)是否启用项目长期记忆(Memory)召回与写入。需先完成项目 Memory 初始化(Shared V2 模式)。
memory_embedding_model_id`string \null`可选"text-embedding-v3"Memory 关联的 Embedding 模型 ID,须与项目 Memory 实际初始化的模型一致。
memory_embedding_dimensions`integer \null`可选(> 0)1024Memory 关联的向量维度(如 text-embedding-v3 对应 1024 维)。
powercontext_enabledboolean首次保存必填false(与 memory_enabled 互斥)是否启用 PowerContext 持久上下文服务。**与 memory_enabled 严格互斥**,同一请求同时设为 true 将被服务端拒绝(HTTP 400)。
config_hashstring只读输出字段"cfg_9f8e7d6c5b4a3210"服务端计算的当前配置快照哈希。用于识别配置版本,**切勿作为 PATCH /config 的输入字段传回**。

角色、入口与关联关系

配置与词库治理接口及权限速查表

功能模块控制台操作位置REST API 端点所需角色 / API Key Scope是否需要 userId生效时机说明
列出可用模型工作台右栏 → 模型(Model) 下拉框GET /v1/agent-runtime/project/models角色:owner、admin、developer、editor<br/>Scope:agent-runtime.project不需要(项目共享)在 **模型(/llm-gateway)** 中新增或启用 Chat 模型后立即可见
读取 / 更新运行配置工作台右栏 → 提示词、参数与能力开关面板GET /v1/agent-runtime/project/config<br/>PATCH /v1/agent-runtime/project/config角色:owner、admin、developer、editor<br/>Scope:agent-runtime.project不需要(项目共享)保存成功后对新创建的 Run 立即生效;不影响正在运行的 Run
查看上下文精简记录工作台中栏 → 对话时间线中的「上下文已精简」节点GET /v1/agent-runtime/project/threads/{threadId}/context-compactions角色:owner、admin、developer、editor、analyst<br/>Scope:agent-runtime.project必填(Query 参数 ?userId=...)当会话历史触发自动精简时实时写入,最多返回 1000 条上下文事件
绑定项目干预词库工作台右栏 → 词库设置(Lexicons) 区域GET /v1/agent-runtime/project/lexicons<br/>PUT /v1/agent-runtime/project/lexicons角色:owner、admin、developer、editor<br/>Scope:agent-runtime.project不需要(项目共享)PUT 整体替换绑定关系后,下一轮对话立即应用改写与 stopIntercept 拦截

功能详解与操作指南

1. 选择 DashScope 对话模型并调整采样与系统提示词

   你是 Agentbase 企业智能客服与技术支持专家(服务于「企业智能客服与知识中台」项目)。
   请严格遵守以下工作准则:
   1. 回答关于 OceanBase 架构、向量索引排障(如 4013/4024 错误码)、AI 网关路由计费及客服 SOP 的问题时,必须优先调用知识库检索工具查阅《kb_enterprise_support》中的权威文档,并在回答中明确引用来源文档标题。
   2. 若检索结果与用户问题无关或证据不足,请如实说明“当前知识库暂无相关记录,建议提交人工工单”,严禁编造配置参数、SQL 视图名或价格数字。
   3. 涉及订单或工单状态查询时,请调用已绑定的 AI Gateway 业务工具获取实时状态。
   curl -fsSL -X PATCH "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
     -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
     -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "system_prompt": "你是 Agentbase 企业智能客服与技术支持专家,请严格基于知识库证据与工具返回结果回答问题,并在结尾标注参考来源。",
       "model_parameters": {
         "temperature": 0.2,
         "top_p": 0.9
       }
     }'

2. 规划上下文窗口预算与理解自动上下文精简(Context Compaction)

1. 为什么不能把整个 context_window_tokens 都留给用户输入?

在每一次 ReAct 模型调用步骤中,送入大模型的总输入 Token 由以下五部分共同瓜分: $$\text{Total Input Tokens} = T_{\text{system\_prompt}} + T_{\text{tool\_schemas}} + T_{\text{memory\_recall}} + T_{\text{history\_or\_summary}} + T_{\text{fresh\_tail}}$$ 而且必须满足: $$\text{Total Input Tokens} + \text{reserved\_output\_tokens} \le \text{context\_window\_tokens}$$ 因此:

2. 自动上下文精简(Context Compaction)的工作机制与审计查询

当用户在同一个会话(Thread)中连续进行了十几轮排障问答并多次调用知识库检索后,累积的历史消息 Token 数会逼近输入预算上限。此时 Agent Runtime 会自动触发上下文精简(Context Compaction):

     curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/threads/thd_01j8x9k2m4n6p8q0r2s4t6u8v0/context-compactions?userId=user_zhangwei_001" \
       -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
       -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

**预期成功响应(HTTP 200 OK)**:

     {
       "items": [
         {
           "run_id": "run_01j8x9k5a7b9c1d3e5f7g9h1j3",
           "event_seq": 14,
           "type": "CONTEXT_COMPACTION_STARTED",
           "payload": [],
           "created_at": "2026-10-22T09:28:10Z"
         },
         {
           "run_id": "run_01j8x9k5a7b9c1d3e5f7g9h1j3",
           "event_seq": 18,
           "type": "CONTEXT_COMPACTION_COMPLETED",
           "payload": [],
           "created_at": "2026-10-22T09:28:12Z"
         }
       ]
     }

说明:出于隐私与载荷体积控制,该公开接口返回精简生命周期事件时间线(含 CONTEXT_COMPACTION_STARTED、CONTEXT_COMPACTION_COMPLETED、CONTEXT_COMPACTION_FAILED 以及辅助对齐时间线的 RUN_FINISHED / RUN_ERROR),正常完成时 payload 为空数组 [],失败时 payload 为包含 code: "CONTEXT_COMPACTION_FAILED" 的错误对象,不直接回显内部摘要全文。


3. 绑定项目级干预词库并启用停用词前置合规拦截(/v1/agent-runtime/project/lexicons)

在项目 enterprise-ai-hub-210 的 **知识库 → 词库(/knowledge-base/lexicons)** 中创建好同义词词典 lex_enterprise_synonyms 与停用词/敏感拦截词典 lex_support_stopwords 后(词条创建详见项目级词库与检索/图谱/智能体协同治理),即可将它们挂载至智能体工作台。

1. 智能体词库绑定的双重作用

2. 配置词库绑定参数说明表

字段名称类型必填默认值说明与约束
enabledboolean否false是否启用当前项目智能体工作台的词库改写与停用词拦截。
stopInterceptboolean否true当用户输入命中已启用词库中的 stop 类型词条时,是否立即短路阻断当前 Run。
stopReplystring否""触发 stopIntercept 阻断时,直接作为智能体回答返回给用户的固定合规话术(最长 4,096 字符)。
bindingsobject[]是[]有序词库绑定数组(最多 100 项),每项包含 lexiconId(词库 ID)与 priority(优先级正整数,1 最高,按升序依次执行)。

3. 通过 API 绑定并验证词库拦截(PUT / GET /v1/agent-runtime/project/lexicons)

# 1. 为项目智能体工作台绑定两本词库并开启 stopIntercept 合规拦截(无需传 userId)
curl -fsSL -X PUT "${APPBASE_ENDPOINT}/agent-runtime/project/lexicons" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "stopIntercept": true,
    "stopReply": "抱歉,您的提问包含受限词汇或违反企业安全合规规范的指令,请围绕产品技术架构、排障手册与客户服务业务进行咨询。",
    "bindings": [
      {
        "lexiconId": "lex_enterprise_synonyms",
        "priority": 1
      },
      {
        "lexiconId": "lex_support_stopwords",
        "priority": 2
      }
    ]
  }'

**预期成功响应(HTTP 200 OK)**:

{
  "enabled": true,
  "stopIntercept": true,
  "stopReply": "抱歉,您的提问包含受限词汇或违反企业安全合规规范的指令,请围绕产品技术架构、排障手册与客户服务业务进行咨询。",
  "bindings": [
    {
      "lexiconId": "lex_enterprise_synonyms",
      "name": "企业智能客服同义词与专有名词词典",
      "priority": 1,
      "enabled": true
    },
    {
      "lexiconId": "lex_support_stopwords",
      "name": "企业客服停用词与敏感拦截词典",
      "priority": 2,
      "enabled": true
    }
  ]
}
# 2. 随时读取当前工作台已生效的词库绑定配置
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/lexicons" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

常见问题与排障

Q1:为什么运行任务时失败并返回 CONTEXT_BUDGET_EXCEEDED 或 CONTEXT_FRESH_TAIL_TOO_LARGE?

原因与排查步骤: 这两个错误码均表示单步模型输入超出了当前配置的可用上下文窗口预算,即使触发自动上下文精简也无法塞入模型窗口:

Q2:在控制台修改了 system_prompt 或切换了模型,为什么正在运行中的那个对话没有按新提示词回答?

原因与排查步骤: 这是 Agent Runtime 的运行期配置快照隔离设计。为了保证单次多步 ReAct 推理过程中模型能力、窗口预算与工具集合的前后一致性,Runtime 会在 POST /runs 受理任务的瞬间锁定当次 Config。在配置面板看到「所有更改已保存」后,直接发送下一条新消息(触发新的 Run)即可使用更新后的配置。

Q3:为什么我的正常业务提问也被词库直接拦截并返回了 stopReply?

原因与排查步骤: 说明所绑定的词库(如 lex_support_stopwords)中,将某个常用的普通口语词(如 “请问”、“帮我查下”)录入为了 stop 类型词条,同时智能体词库绑定又开启了 stopIntercept: true。

Q4:调用 PATCH /v1/agent-runtime/project/config 时只传了 {"model_parameters": {"temperature": 0.5}},为什么之前设置的 top_p 变成了默认值?

原因与排查步骤: PATCH /config 对顶层字段(如 system_prompt、max_steps、model_parameters)执行局部保留更新,但对嵌套的 **model_parameters 对象采用整体替换(Replace)而非逐键合并(Deep Merge)**。因此更新采样参数时,请始终同时传入完整的 {"temperature": 0.5, "top_p": 0.9}。


相关文档