2.9.0 迭代增量与版本记录
| 版本 | 2.9.0 |
|---|---|
| 源 tag / 仓库 | v2.9.0(peeled commit ebae954094883b847bf582cfbe9fbe58ae0a7499)@ git@code.alipay.com:obai/appbase.git |
| 本迭代源 commit | ebae954094883b847bf582cfbe9fbe58ae0a7499(tag 即 release-2.9.0 尖端) |
| 上一迭代源 commit | ea835e462085decbbf49ab7fd6a0e99928be72a9(v2.8.0 tag) |
| 文档基线 commit | a6e9277beef79d75d4efbfc5dde011ab68eb5d95(迭代分支 v2.9.0 自 origin/master 冻结) |
| 生成日期 | 2026-10-12 |
| 服务版本 / Migration | APP_VERSION_STABLE 单次 bump 2.8.0 → 2.9.0(无 2.8.x 中间 cut);Migration V56(审核二期项目 schema、LLM Gateway 按模型参数 modelMetadata、知识索引存储 Version 定义协调、KB 摄取追踪懒展开、计量 quantity INT→BIGINT;升级迁移基线 1.9.0 不变) |
新增能力
内容审核二期(异步后置审核)(影响面:Server API / SDK;Console 面为表内状态徽标):资源审核模式在
pre(同步前置)之外新增post(先落库再异步审核)与hybrid(短文本同步、超长文本异步,按平台moderation.limits.textMaxLength分流);二期整体由平台 Admin 开关moderation.phase2.enabled控制,默认关闭,未开启时post/hybrid行为等同pre。新增「违规转人工复核」开关requireManualReviewOnViolation(默认 true:违规内容进入隔离(quarantined);false 时仅创建者可见的私密扣留(private_hold))。文档新增moderationStatus(checking / pending / private_hold / quarantined / published / action_error)等字段;读路径对非创建者隐藏未发布文档并修正列表总数;事件在发布后补发。数据表行内展示审核状态徽标(审核中 / 待审核 / 已拦截 / 审核异常 / 审核失败)。LLM Gateway 厂商预置模型目录(影响面:Console / Server API / SDK):新增
GET /v1/llm-gateway/provider-presets——内置 24 个厂商预设、313 个预置模型(OpenAI / Anthropic 官方与 API-Compatible、火山方舟(豆包)、xAI、智谱、Moonshot、DeepSeek、MiniMax、Gemini、OpenRouter、StepFun、NVIDIA NIM、LongCat、通义千问 DashScope、Azure OpenAI、Ollama、vLLM、LM Studio、Xinference、GPUStack、ModelScope 等自托管类)。Console「添加提供商」选择厂商预设后自动填充 Base URL 并可导入内置模型列表(含按模型参数:上下文窗口、最大输出、Embedding 维度与输入上限、工具调用、多模态 Embedding);手动配置项仅指定协议。Provider 可保存按模型的modelMetadata;模型目录合并预设与存储值,供内部调用(知识库索引、Memory 等)代替硬编码默认值。Provider 类型新增volcengine(含多模态 Embedding 专有端点)与openai-official/anthropic-official;模型编辑与添加统一为同一交互。Observability 观测(Observation)列表(影响面:Console / Server API / SDK):新增跨链路的观测列表页与
GET /v1/observability/observations:按名称精确匹配、观测类型多选、时间范围、级别、traceId、environment 过滤;limit1–100、offset 按 limit 整数倍稳定分页,返回{ observations, total }。知识库解析评估(解析与分块质量)(影响面:Console / Server API):评估任务类型新增「知识索引质量」——对解析按完整性、忠实度、结构三维评分,对分块按边界、上下文、独立完整性、大小、冗余五维评分,解析分与分块分各占最终得分 50%;严重错误 capped(严重问题将综合分压至 ≤0.5)。需要知识库开启摄取追踪(
tracingEnabled,知识库创建参数与设置开关;依赖平台管理员全局开关)并重新摄取以生成完整评估证据;评分明细支持逐页 / 逐块下钻(GET /v1/observability/scores/{scoreId}/quality-details)。PDF / 图片页证据可配置视觉评估模型。评分根因分析与证据化归因(影响面:Console / Server API):评分详情新增异步根因分析——自动链路只处理关联 Trace、可归一化且
normalizedValue < 0.5的数值评分;用户也可把任意可归一化、关联 Trace 的数值评分选为人工 bad case 触发分析(不受低分门槛限制)。分析基于评分理由、关联 Trace / Observation 与规范化轨迹,以确定性规则返回观测事实、根因(置信度:已确认 / 很可能 / 可能)与修改建议;可选开启「使用模型进行根因分析」(GET/PUT /v1/observability/evals/root-cause-analysis-settings,需先配置默认评估模型,规则结果兜底)。「分析洞察」列表以只读批量摘要展示根因与建议(POST /observability/scores/analysis/summaries),批量触发接口单批最多 100 个评分(POST /observability/scores/analysis/trigger)。自定义评估模板可配置证据化归因:归因阈值((0, 0.5],默认 0.5)+ 归因标签 JSON(PATCH /v1/observability/evals/templates/{templateId}/attribution),把有证据支持的根因映射到业务标签。评估模板版本、多标签与执行重试(影响面:Console / Server API / SDK):自定义评估模板支持多版本(新版本保留名称与语言,历史评估继续使用原版本)与多标签分类筛选(最多 20 个标签、每个 ≤40 字符,内置模板已分类;替代原「维度」展示);模板目录可删除单版本(历史任务仍可查看所引用版本)。评估任务新增执行重试(
POST /v1/observability/evals/jobs/{jobId}/executions/{executionId}/retry,复用仍有效的已保存进度)。Memory 评估支持按流水线阶段(事实抽取、画像、技能蒸馏等 10 类)建任务;数据集条目按问题 / 答案(JSON 输入 / 参考输出)+ 元数据存储,新增数据集报表(延迟、成本与评分对比)。新增错误码OBSERVABILITY_EVAL_TEMPLATE_NOT_FOUND(404)。Functions 执行路径查询(影响面:Console / Server API / SDK):新增
GET /v1/functions/{functionId}/execution-paths(分页列出已产生执行记录的去重请求路径,字符串升序)与GET /v1/functions/{functionId}/execution-paths/executions(按完整 path 精确匹配分页查询执行记录);失败执行的业务日志随 execution 持久化保留,Console 可区分平台失败与业务失败(平台内部 / 平台依赖 / 沙箱创建为 503、沙箱启动超时 504、沙箱链路异常 502,业务异常保持 500)。知识库构建与检索增强(影响面:Console / Server API / SDK):检索新增答案合成(
answer=true:用知识库 indexingDefaults 的 chat 模型对合并证据做接地合成,最多 12 行证据、答案 ≤1024 tokens,结果带answer状态 / 文本 / 模型 / 延迟);创建知识库可指定 Embedding 维度(对模型探测校验,不符则创建失败);GraphRAG 与 Wiki 支持自定义提示词(实体抽取 / 描述摘要 / 社区报告提示词,留空回退内置模板;Wiki 按页面类型配置自定义提示词);索引操作支持并发 / 批量 / 缓冲操作控制(如graphragEmbedBatchSize、wikiPageMaxConcurrent等,显式值仅保存上限内合法整数,未提供回落 worker 环境);文档层级标签(斜杠父子标签、标签树目录、平铺 / 标签树两种视图、按名称或标签搜索)。PowerContext(托管上下文)(影响面:Console / Server API):原生 PowerContext API 增加项目级路径(
/v1/projects/{projectId}/powercontext/**,scopepowercontext.execute;原有路径保留);托管上下文的模型调用改为经 LLM Gateway 直连(受限服务身份鉴权),请求 trace 导出至观测链路;入口可用性改为仅跟随部署开关(项目支持情况在初始化时校验,API 返回availability {supported, reason})。Console 面命名统一为「上下文」(启用上下文、主体记忆等),仅 Shared V2 项目可初始化。
行为变化
数据表与文档的审核读隔离(影响面:Server API):二期模式下未发布(checking / pending / private_hold / quarantined)文档对非创建者隐藏,列表
total同步修正;审核任务卡死由 reconcile 任务按当前配置语义重判修复(配置缺失默认requireManualReviewOnViolation=true→ 倾向隔离)。修复大页列表审核查询超限导致的 500。评估模板目录结构(影响面:Console):4 个 Memory 内置模板(经验蒸馏质量 / 事实抽取质量 / 语言保持 / 技能蒸馏质量)被 Memory 评估任务类型(按流水线阶段)替代,不再出现在模板目录。
知识索引全链路加固(影响面:Console / 部署):索引启动脱网可用(tiktoken/numba 缓存镜像内烘焙,冷启动 300s 预算);发布门禁与 Wiki 预算硬失败;GraphRAG PERSON 消解不再卡死;传输断连后可恢复构建;V56 对存量知识索引存储补齐 Version 定义(含独立 vectors pool 路由),legacy 库以
versionId IS NULL隔离;MinerU 图片清单压缩防元数据超限。平台与运行时(影响面:Server / 部署):HTTP 请求资源循环引用内存累积修复;多进程池按容器收敛并加 per-process 守护;OceanBase 断连恢复与 Console Markdown 安全渲染;计量批处理与项目活跃更新优化(checkpoint / 日聚合 quantity 扩为 64 位,超 21.4 亿的 byte 计数精确保留);Memory 端到端 tracing 与网关处理性能优化、检索 Trace 明确为零 Generation 的确定性流水线投影。
Agent 回复展示(影响面:Console):Agent Runtime 工作台回复按 Markdown 排版;知识库召回内容中的
/v1/storage/...Markdown 图片用对应项目 API 地址加载,历史消息与流式回复共用同一渲染。
配置与部署
项目元数据库迁移进入
V56:审核二期表结构(仅对已启用审核的项目展开,未启用的 Shared V2 项目保持 lazy,首次使用时引导建表);LLM Gatewayupstream_configs.modelMetadata扩展;知识索引存储 Version 定义协调;KB 摄取追踪懒展开;计量 quantity INT→BIGINT 仅对 console 项目在 project-migrate 阶段执行。曾在 2.9.0 早期预览环境完成 V56 的(缺审核索引修复或计量 Contract),需按迁移手册受控 Full rerun 补齐。SDK 侧精确交付坐标见sdks/changelogs/2.9.0.md。审核二期需运维侧启用
worker-moderation-jobsworker 与moderation-jobs-reconcile周期任务;平台开关moderation.phase2.enabled与moderation.limits.textMaxLength仅 Admin 动态配置(无 ENV)。知识索引操作控制的支持字段、范围与 Helm 映射以知识索引 Worker 配置矩阵为准;平台环境变量新增
_APP_KNOWLEDGE_BASE_INGESTION_TRACING_ENABLED(摄取追踪全局开关,默认关)。
废弃与迁移
V55已发布不回写;升级到 2.9.0 的项目元数据库变化由V56承接(Server spec 567 → 575 端点,纯新增;Console spec 690 → 702)。pre语义不变;既有pre配置不受二期开关影响。评估模板「维度」字段由标签替代(内置模板已迁移映射;历史评估结果不受影响)。
已知问题
早期 2.9.0 预览环境的 V56 完成标记会跳过后续修复(审核唯一索引替换、计量 BIGINT Contract),升级到含修复镜像后需对受影响范围执行受控 Full rerun(详见 appbase
docs/features/moderation/README.md与迁移手册),本仓仅登记提示。
手册侧(本迭代 products/ 变化)
功能点增删:无新增 / 删除文档;全部为既有页增补。
正文上刷(zh-CN):
moderation.md(新增「异步后置审核与人工复核」小节:post/hybrid 模式、requireManualReviewOnViolation、审核状态语义与表内徽标;模式表从仅 pre 扩为 pre/post/hybrid);models-ai-gateway/llm-gateway.md(Provider 表补厂商预置目录、按模型参数与新 Provider 类型;新增预置模型导入截图);observability/overview.md(页面结构表补 Observation 行与评估解析任务类型);observability/evaluations.md(评估模板标签 / 版本 / 执行重试 / 知识库解析评估要点);observability/metrics.md(Memory 阶段过滤与指标完整性提示);knowledge-base/overview.md(能力表补答案合成、Embedding 维度、文档层级标签、索引操作控制行);knowledge-base/wiki.md(自定义提示词与操作控制、输出语言改名说明);functions.md(执行路径查询与失败日志保留);routes.md(Observability 行补 observations / parsing-quality 路由);memory/overview.md命名与可用性口径同步。逐语言状态:zh-CN 上刷完成;en-US、ja-JP 未产出(骨架态),事实源为中文同名文件。
截图台账:沿用 2.8.0 实拍 28 张(页面结构未变的图不重拍);本迭代 2026-10-12 SIT 新增实拍 4 张(1440×900,与存量分辨率一致,单图 ≤300KB,逐张经捕获时 DOM 文本断言确认主区域为预期内容、无错误页、不含凭据):
models-ai-gateway/fig-3-llm-gateway-provider-preset.png(添加提供商弹窗选中火山方舟(豆包)预设后的模型导入列表)、observability/fig-4-observability-observations.png(Observation 列表页真实数据态:名称 / 观测类型 / 起止时间列与 93 条总计)、observability/fig-5-observability-parsing-quality.png(创建评估任务向导的任务类型页:包含「知识库解析评估」任务类型入口)、knowledge-base/fig-3-knowledge-base-doc-tags.png(文档列表的平铺视图 / 标签树目录切换)。SIT 当前部署版本为 2.10.0(页脚实测;本迭代源 tag 为 2.9.0),2.9.0 交付的上述功能在 SIT 均已可见且与源码 diff 一致,截图据实标注。核验缺口:审核二期(post / hybrid、人工复核 disposition)在 SIT 由 Admin 开关默认关闭,Console 无可见管理界面(仅数据表行内徽标,需真实触发异步审核流),本迭代不拍摄、正文只写源码可证语义;评分根因分析与解析评估的有数据结果页(分析洞察、逐页逐块明细)需真实评估任务跑完后补拍,本迭代只拍任务类型入口;摄取追踪依赖平台管理员全局开关,SIT 项目未开启,解析评估执行页未实拍。