AgentbaseDocs
文档目录

常见问题

本章汇总企业在生产环境使用 Agentbase 2.10.0 过程中最常遇到的技术问题、HTTP 错误码诊断矩阵与配置排障方案。内容按架构与存储模式(JsonTable / Shared V2)、认证与 API Key 权限域、模型网关与 DashScope 接入、知识库混合检索与词典绑定、Memory 启用与蒸馏进化、智能体工作台与 AgentOps 可观测性六大专题组织。

功能概述

当开发者或运维人员在 Console 操作受阻、或通过 SDK / REST API 调用数据面接口收到非 2xx 响应时,快速区分“实例部署级限制(Capability)”、“项目级服务开关(Services)”、“权限与凭证范围(RBAC / Scope)”与“上游模型/存储依赖异常”是缩短 MTTR(平均恢复时间)的关键。

本章提供标准化的排障决策路径,帮助研发与运维团队无需翻阅底层源码即可自主定位并解决 95% 以上的常见报错。

排障专题分类涵盖的核心模块与场景典型关联状态码或错误标识
一、架构、版本与存储模式版本核验、SDK 响应格式协商、JsonTable vs Shared V2 表模式转换、项目独立只读栅栏400(格式不匹配)、409(状态冲突)、412(表模式或部署不支持)、503(排空窗口)
二、认证、会话与 API Key 权限域Console 登录 MFA/邮箱验证守卫、API Key Scope 缺失、Dev Key 限制、前端 CORS 拦截401 general_unauthorized_scope、401 user_unauthorized、403(CORS / 平台未登记)
三、模型网关与 DashScope 接入厂商预设导入、API Key 掩码、逻辑模型主备路由、语义缓存未命中、Token 预算超限401(上游厂商 Key 失效)、429(RPM/TPM 或月度预算超限)、502/504(上游超时)
四、知识库混合检索与词典绑定文档解析失败、Embedding 1024 维校验、同义词/停用词词库生效时机、GraphRAG/Wiki 构建中断400(维度不一致)、412(高阶索引未启用)、文档状态 failed
五、Memory 启用与蒸馏进化Shared V2 前置检查、异步写入 jobId 轮询、partial_failed 诊断、四类 Pipeline 与技能二次确认412(非 Shared V2)、LLM_REQUEST_REJECTED、任务状态 partial_failed / failed
六、智能体工作台与 AgentOps 运维工作台 API Key 认证、侧栏隐藏入口(Messaging / Reports)、索引质量评估待复核区、受限身份函数报错沙箱 502/503/504、评估状态 pending_review、报表空面板说明

核心概念与架构

在排查任何 Agentbase 控制台或接口异常时,建议遵循系统请求处理链路的五层门禁诊断模型。请求只有依次通过以下五道关卡,才会真正执行底层业务逻辑:

flowchart TB
    Req["客户端 / 服务端 / 控制台发起请求"] --> Gate1

    subgraph Gate1["第 1 层:协议版本与来源校验"]
        C1{"1. X-Appwrite-Response-Format 兼容?<br/>2. 客户端 Origin 命中已登记 Platform?"}
    end

    subgraph Gate2["第 2 层:身份认证与权限域 (Auth & Scope)"]
        C2{"1. Console Session 具备写角色?<br/>2. Server API Key 包含目标 Scope?<br/>3. Client 用户命中表/行/桶 ACL?"}
    end

    subgraph Gate3["第 3 层:部署 Capability 与项目开关"]
        C3{"1. 部署级环境变量已开启 (非 412)?<br/>2. 项目 Settings -> Services 已打开?<br/>3. 项目存储模式满足要求 (如 Shared V2)?"}
    end

    subgraph Gate4["第 4 层:平台配额、限流与只读栅栏"]
        C4{"1. 未触发 Quota / Ratelimit / Token 预算?<br/>2. 未处于 databaseReadOnly / storageReadOnly?"}
    end

    subgraph Gate5["第 5 层:业务执行与上下游依赖"]
        C5["执行 OceanBase 读写 / ACS 云函数沙箱 /<br/>DashScope 模型推理 / 异步 Worker 任务"]
    end

    C1 -- "否" --> E1["返回 400 格式错误 或 401/CORS 拒绝"]
    C1 -- "是" --> Gate2
    C2 -- "否" --> E2["返回 401 unauthorized_scope 或 404/空列表"]
    C2 -- "是" --> Gate3
    C3 -- "否" --> E3["返回 412 Precondition Failed 或服务不可达"]
    C3 -- "是" --> Gate4
    C4 -- "否" --> E4["返回 429 限流 / 403 project_*_read_only / 503"]
    C4 -- "是" --> Gate5

全局高频 HTTP 状态码与错误类型速查表

HTTP 状态码错误 type 或特征标识根因归属层级标准处置动作
400general_argument_invalid / 响应格式不匹配协议与参数层检查必填参数、字段长度约束;若使用自研 SDK(如 agentbase-node-sdk@2.10.0),确保发送 X-AppBase-SDK: true 与 X-Appwrite-Response-Format: 2.10.0。
401general_unauthorized_scopeAPI Key 权限层进入项目 Overview → Integrations → API keys,为该 Key 补充勾选缺失的 Scope(如 users.read、databases.write)。
401user_unauthorized / CORS 报错来源与会话层服务端检查 X-Appwrite-Key 是否正确传入;前端 Web/移动端检查是否在 Overview → Platforms 中登记了当前 Hostname 或包名。
403project_database_read_only / project_storage_read_only平台只读治理层当前项目被平台管理员置为数据库只读或文件存储只读状态;单行/单文件立即删除仍可执行,常规写入需联系管理员解除只读后再试。
409document_already_exists / 状态版本冲突并发与幂等层自定义 $id 重复,或更新 Memory 记忆 / 切换只读状态时传入的期望版本号(version / expectedDatabase)与线上最新状态不一致,需先重读最新记录。
412Precondition Failed(Capability 或前置条件未就绪)部署能力与前置层1. 实例未部署该可选能力(如高阶索引或 Sites);<br/>2. 项目表模式不是 Shared V2(无法启用 Memory);<br/>3. 尚未配置必需的模型 Provider。
429general_rate_limit_exceeded / Gateway Token 超限限流与预算层触发平台请求速率限制或 LLM Gateway Key 的月度 Token 预算/RPM 阈值;开发环境可使用 Dev Key,生产环境需调高配额或做退避重试。
502 / 503 / 504函数沙箱异常 / 只读切换排空窗口 / 上游模型超时执行与基础设施层区分平台级错误(函数沙箱创建 503、启动超时 504、只读切换排空 503)与业务代码异常(500);对 503 排空窗口执行指数退避重试。

角色、入口与关联关系

不同类别的线上问题需要在 Console 的对应治理页面中进行核查与修复。下表列出了各排障场景对应的控制台入口与所需角色权限:

排障场景控制台核查入口精确路由路径修复所需角色 / 权限
核查账号 MFA、恢复码与待删项目恢复顶部导航 Account/console/account(Overview / Sessions / Project cleanup / Table mode conversions)账号本人(项目恢复需组织 owner)
核查前端跨域与 API Key Scope项目 Overview → Integrations/console/project-{region}-{project}/overview/platforms · .../api-keysowner / admin / developer / editor(platforms.write / keys.write)
核查项目表模式与客户端服务开关项目 Settings → Overview/console/project-{region}-{project}/settingsowner / admin / developer / editor(列删除仅限 owner)
核查 30 日用量缺失与配额水位项目 Metering / 组织 Usage/console/project-{region}-{project}/usage/aggregates任意项目成员(含 billing / analyst 只读角色)
核查模型供应商连通性与 Key 预算项目 模型(Models) / AI 网关/console/project-{region}-{project}/llm-gateway · .../ai-gateway具备模型与网关写权限的项目成员
核查慢请求、低分回复与解析评估项目 智能体运维(AgentOps)/console/project-{region}-{project}/observability · /logs任意项目成员(发起评估任务需写权限)

功能详解与操作指南

本节按六大生产专题,逐一解答高频疑难问题并提供分步操作指引。

专题一:架构、版本兼容性与存储模式(JsonTable / Shared V2)

1. 如何准确核验当前部署实例的服务端版本?为什么 SDK 请求会报响应格式不匹配?

2. 项目的共享表(JsonTable)、独占表与 OceanBase Shared V2 表模式如何选择与转换?

3. 写入数据库或上传文件时报错 project_database_read_only / project_storage_read_only 或 503 是什么原因?

专题二:认证、会话、侧栏可见性与 API Key 权限域

4. 为什么控制台左侧边栏看不到“AI 网关”、“消息(Messaging)”、“站点(Sites)”或“报表(Reports)”?

不同入口的隐藏原因各不相同,请按以下清单对号入座:

5. 登录后不断跳回登录页,或被强制重定向到 /console/verify-email / /console/mfa?

专题三:模型网关、AI 网关与 DashScope 接入

6. LLM Gateway(模型)与 AI Gateway(统一 AI 网关)有什么区别?凭据能否混用?

专题四:知识库混合检索、词库干预与高阶索引

7. 知识库绑定同义词词典與停用词词典后,需要重新上传并切片全部文档吗? GraphRAG / Wiki 构建卡住怎么办?

专题五:Memory 长期记忆启用、异步写入与技能蒸馏

8. 为什么 Memory 写入接口返回 HTTP 202 后查询不到记忆,或任务状态显示 partial_failed?

专题六:智能体工作台、云函数与 AgentOps 可观测性

9. 云函数(Functions)执行失败如何区分是平台沙箱问题还是业务代码 Bug?Java 17 如何直接部署 JAR 包?

10. 为什么 AgentOps 知识索引质量评估的某些记录没有生成分数,或者 Reports 报表的 Token 浪费面板为空?

版本与兼容性

如何确认部署版本? 调用公开端点 GET /v1/health/version 读取目标实例版本。服务版本为 2.10.0 时应返回 {"version":"2.10.0"};不要用本地源码版本或其他环境的结果代替目标实例读回。

SDK 请求报响应格式不匹配? Agentbase 自研 SDK 的客户端应发送 X-AppBase-SDK: true,并让 X-Appwrite-Response-Format 匹配目标实例的服务版本(例如 2.10.0 实例使用 2.10.0);官方 Appwrite SDK 使用独立兼容上限(默认最高 1.9.0)。严格模式下不匹配的请求被拒,宽松模式仅在响应头 X-Appwrite-Warning 提示。具体行为以部署环境变量为准。

常见问题与排障

除上述六大专题外,以下补充三条跨模块运维高频问答:

Q1:最近 30 个 UTC 日用量视图(Usage Aggregates)中某天显示“缺失(Missing)”或“不完整(Incomplete)”是什么含义?

原因与排查步骤: Agentbase 在账号、组织、项目三级提供的 30 个 UTC 日聚合视图严格区分 **真实用量为 0 与 计量数据缺失/不完整**。当底层计量源延迟、检查点缺失或子范围未对齐时,界面会明确标注“不完整”及具体原因,绝不会将缺失的数据错误渲染为 0。遇到“不完整”提示时,请参考页面标注的原因等待计量水位追平,切勿以不完整状态下的偏小数值作为最终账单核算依据。

Q2:在组织 Project cleanup 页面批量删除了不活跃项目,后悔了还能救回吗?

原因与排查步骤: 可以恢复,但必须在后台物理清理任务正式开始前操作。组织 Owner 在 Organization → Project cleanup 提交删除后,项目先进入 Pending deletion(待删除)缓冲态。请立即前往顶部导航 Account(账号中心) → Project cleanup 页签,在待删除列表中找到目标项目,确认其状态仍为 Pending(尚未进入 Purging),点击右侧 Restore 按钮即可取消物理删除并无损恢复全部项目资源。

Q3:如何快速查找某个具体 HTTP 请求路径在云函数中的所有历史执行记录?

原因与排查步骤: 无需逐页翻找全量执行流水。进入目标 Function → Executions 页面,使用执行路径查询(Execution Paths)功能:先分页浏览去重后的请求路径列表(按字典序排列),并在 2.10.0 中支持按 path(完整路径精确匹配或正则匹配 pathMatch=exact|regex)与 method(如 POST、GET)过滤,选中目标路径后即可直接下钻查看该路径下的全部历史执行耗时、响应码与日志。

相关文档