这一期迭代日记拖了两周才动笔。不是没素材恰恰是素材太多——准确地说是被两个“半成品”状态折腾得够呛需求文档写得漂漂亮亮排期评审时却被挤了出去资源申请单审批流程已经走完底层环境的权限却迟迟没有开通。干过企业级AI项目的人都懂这种“卡在半路”的状态比直接失败还磨人。我们团队在做一个本地部署的企业级知识库助手技术栈以Java为主核心是基于大模型做检索增强生成RAG同时把Agent能力Function Calling、任务编排、工具调用逐步集成进去。从0到1搭起来前后跑了二十多个月这个Vol.108就是这二十多个月里的第108次迭代复盘。如果你也在做企业级AI应用或者你的团队正在经历“写好的东西进不了版本、批下来的资源看得见用不上”这类问题这期内容值得你花十分钟看完。我会把两件事拆开讲为什么会出现这两种半拉子状态以及我们是怎么从流程和技术两个维度去处理的。顺便把最近摸底排查中关于本地知识库助手、Java Agent平台、测试用例跨项目组复用这三个方向和这次迭代的关联也一并记录下来。1. 先说结论这期迭代我们卡在了两个“半拉子”上1.1 核心卡点方案写了没进去审批批了没完成这期迭代启动前团队梳理了上个迭代遗留的12个Badcase其中用户集中反馈的问题是知识库召回不准。有人问“上个月的报销政策是什么”系统却把去年同月的政策返回来了。负责检索的同事花了两天时间定位、分析最后给出了一套完整的RAG优化方案在向量检索的基础上加BM25关键词召回再做交叉编码器Rerank同时调整文档切分的chunk size和overlap参数。方案组织了三方评审技术负责人、算法负责人、安全合规都签了字结论是“同意”。但到了产品经理排期的时候问题就来了——这个优化需要动检索服务的核心链路要算法工程师深度配合还要额外的GPU资源做Rerank模型的推理而这两个条件当期的迭代都满足不了。结果就是方案写了评审批了但没排进迭代。另一边是资源申请的审批。为了做Rerank模型的效果评测我们按流程提交了GPU资源扩容申请。审批流走得很顺利从项目负责人到部门负责人一路绿灯流程状态变成了“已通过”。但真实情况是审批通过后还需要运维团队从资源池里分配节点、配置网络策略、开通白名单甚至要等机房那边完成物理机器的上架。这些后置环节没有一个被审批系统跟踪也没有SLA约束。于是审批状态显示“已通过”但团队的训练任务还在排队。卡点类型具体表现卡住的位置造成的后果写了但没写进去RAG召回优化方案评审通过未进入迭代排期版本规划阶段功能晚一个迭代用户反馈的badcase继续堆积批了但没批完GPU资源扩容审批通过环境权限未开通审批之后的环境配置训练评测任务排队迭代速度明显下降1.2 一个共性两边都缺“最后一公里”这两个问题表面看一个是排期问题一个是资源问题但往深了想它们其实是同一个病根大家都以为某个节点结束就是完成了但实际工作并没有闭环。方案评审通过不等于需求进了迭代。从评审到排期之间还隔着人力确认、优先级排序、资源预留、依赖检查。审批通过不等于资源可用。从审批到下发的链路更长资源分配、网络打通、权限配置、环境验证每一步都可能成为黑洞。企业级AI项目的依赖链条尤其长模型、数据、GPU、审批、安全审查、基础设施任何一个环节掉链子前面的工作全部白费。明白了这个底层逻辑之后后面所有的处理手段就有了方向。我们先从最痛的那个点讲起——“写了但没写进去”。2. “写了但没写进去”从方案到主干隔着一整个沼泽2.1 场景回放RAG优化方案为什么进不了排期先还原一下RAG优化方案是怎么“写了没写进去”的。负责检索的同事A发现Badcase集中在“时间敏感的Query”上比如报销政策、年假规定、绩效考核周期。这类问题有一个特点用户问的是“当前时间点”的规则而文档库里存在多个历史版本单纯的向量检索会把语义相近的历史文本一并捞出来再经过大模型汇总就容易出现“新旧政策混淆”。A同事给出的方案分三层检索层改为BM25关键词检索 向量检索的混合召回让“报销”这类关键词的精确匹配结果也能进入候选集而不完全依赖语义相似度。排序层引入交叉编码器Rerank对召回的前50条结果做精排让“政策版本时间”和“当前时间”的匹配度成为排序的重要特征。切分层调整文档切分的策略把政策类文档按“章节生效日期”切分而不是简单按固定长度切块保证每个chunk自带时间上下文。技术评审时这个方案没有任何异议大家都觉得方向正确、收益可预期。但问题出在排期阶段检索服务的改动需要大量联调Rerank模型需要先做量化压缩才能在CPU上跑否则就得申请额外的GPU资源而这些工作恰恰不在本迭代的容量里。产品经理手里已经排了三个需求都是安全合规要求的硬任务于是这个优化方案被顺延到了下个迭代。2.2 合入被卡的三种典型姿势“写了但没写进去”不只是排期层面代码层面的合入被卡更常见。这期我们专门把历次迭代踩过的合入阻塞点梳理了一遍基本可以归结为三种姿势姿势一代码写完了但功能开关被环境配置钳制。开发在最开始写代码时没考虑配置项上线时需要手动在配置中心添加开关结果运维不知道这个新配置默认没有打开。姿势二依赖的新数据源需要权限申请但申请流程走了一半没人跟进。我们曾经做过一个数据服务对接代码早就合入了主干但生产环境的数据源白名单没开导致接口在联调时一直报403最后查了半天发现是权限配置的问题。姿势三测试资源被其他项目组占用回归测试排不上队。这个在企业级项目里特别常见多个项目组共用一套测试环境高峰期需要抢时段。这三种姿势有一个共同特征它们都不在“开发-提交-评审”这条常规链路上而是在代码评审完成到功能上线之间的“灰色地带”。这部分的推进责任没有明确归属往往靠某个人的自觉或者偶然提起才能被执行。2.3 我们的解法Feature Flag、前置依赖确认、排期容量控制这期迭代我们做了三个调整目前已初见成效。第一个调整全面启用Feature Flag机制。所有新功能在代码合入时默认带一个配置开关未验证完成前保持关闭状态。这样就算代码提前合入主干也不会暴露给用户相当于把“能不能合入主干”和“能不能上线”两件事解耦了代码层面的合入阻塞大幅减少。在Java服务里我们用Nacos做配置中心开关挂了两个配置ConfigurationProperties(prefix feature.flags) Component Data public class FeatureFlagConfig { private boolean ragHybridRetrieval false; private boolean agentToolOaQuery true; }接口层面再套一层开关判断比如知识库检索逻辑里这样写Service public class RetrievalService { Autowired private FeatureFlagConfig featureFlagConfig; public ListDocument retrieve(String query) { if (featureFlagConfig.isRagHybridRetrieval()) { // 新逻辑混合检索 rerank return hybridRetrieve(query); } else { // 旧逻辑纯向量检索 return vectorRetrieve(query); } } }这样做的收益是明显的功能开发完就可以进主干不阻塞后续的增量开发。真正验收之前开关一直是关闭状态灰度验证完再逐步放量。第二个调整把依赖确认前置到需求评审阶段。现在排期检查表多了一栏“外部依赖是否已申请”包括数据源权限、测试环境、GPU资源、安全评审排期等。只有这一栏打勾需求才能进入迭代承诺列表。第三个调整控制单迭代的需求数量。我们以前比较理想化觉得团队能扛总想多排几个需求。现在的原则是“砍掉一半保障核心”宁可少排一个需求也要保证排进去的每个需求都有充足的人力完成并验证。3. “批了但没批完”审批流比代码更会拖3.1 场景回放GPU资源申请“已批准”却“未开通”继续说GPU那个事。我们的审批流是标准的OA流程申请人提交 → 项目负责人审批 → 部门负责人审批 → 财务/预算确认 → 资源管理员分配。整个过程在系统里一共用了3天状态全部通过。但问题出在状态“全部通过”之后的阶段。审批流程结束后还需要资源管理员在虚拟化平台上创建实例。这一步没有自动化管理员同时维护着几十个申请单优先级完全靠他自己的判断。我们的申请单标注的是“测试环境用”优先级被排到了后面结果从审批通过到实例真正可用又花了整整9个工作日。这种“批了但没批完”的现象在企业级项目里太普遍了。审批系统只负责流程审批不负责后续交付。审批通过之后系统就没有记录所有人都不知道下一步该做什么。尤其是涉及多个职能团队协作时信息在团队之间一交接就断掉等待时间全成了隐形消耗。3.2 审批流的隐形环节有多隐形我们认真梳理了一次GPU资源申请的全链路发现从发起申请到实例真正可用中间隔了7个环节提交审批单申请人填单上传理由说明通常半天。项目负责人审批确认需求的优先级半天到一天。预算审批确认成本归属通常需要财务部门的预算负责人审一次。安全合规确认确认资源用途是否合规这部分在数据安全要求高的企业里尤其严格。资源池检查运维确认是否有可分配的节点。实例创建虚拟化平台创建虚拟机配置网络策略、存储、白名单。环境验证申请人测试连通性确认SSH可登录、API可用。前面几个环节在审批系统里有记录但“实例创建”和“环境验证”这两个环节完全游离在外。资源管理员手动操作完不会自动通知申请人申请人在OA里看到的状态永远是“已通过”但实际工作没有结束。3.3 把审批当接口来治理这个问题的解法我们参考了系统开发里的一个思路——定义好接口契约然后加上超时熔断和监控。具体做法分三步第一步把审批通过后的后置环节显性化。我们和运维团队一起定义了一份《审批后置任务清单》每个审批类型在通过后自动创建一条跟进记录明确后续要完成的动作、责任人和目标完成时间。第二步建立SLA监控。状态为“已通过”但超过2个工作日实例未交付的自动升级到运维负责人超过5个工作日未交付的升级到项目总监和信息部门负责人。第三步做一个小工具把各个系统的状态串起来。受限于公司的系统开放程度我们先用了一个折中方案用Python写一个定时爬虫每天扫描OA系统的审批状态和运维工单系统的交付状态然后把数据汇总到一张电子表格里。有两类异常会被标红# 伪代码审批状态扫描逻辑 for task in oa_tasks: if task.approval_status PASSED: delivery_status get_delivery_status(task.id) if delivery_status is None: mark_red(task, 审批通过但未找到交付工单) elif delivery_status.elapsed_days 2: mark_red(task, 交付超时) else: mark_green(task)这套机制跑了一个月之后资源交付的平均时长从9个工作日降到了3个工作日以内。更重要的是审批通过后不再是“无人管”的状态每个环节都有人负责、有看板可查、有逾期升级。4. 藏在后面的测试用例我们差点没接住4.1 一个很容易被忽略的坑跨项目组的用例规范冲突这期迭代在验证RAG优化方案时测试团队也暴露了一个老问题——不同项目组的测试用例管理各自为政。我们整个部门下面有多个项目组知识库组、Agent平台组、数据服务组。每个组都有自己的测试用例存放方式有的用Excel有的用在线文档有的直接写在禅道里。模板更是五花八门有的用例有前置条件和预期结果有的只有操作步骤还有的连优先级都没有标。平时每个组测自己的一亩三分地的时候还好但一旦涉及跨组联调问题就来了。这期RAG优化需要知识库组提供测试文档Agent平台组提供查询接口数据服务组提供报销政策的原始数据三个组的用例格式对不上联调用例只能临时重新设计重复劳动严重。4.2 建立统一的Case Library解决“复用”问题我们在这期迭代做了一件事把分散在各部门的用例按“业务能力”维度整理到一个统一的Case Library里而不是按项目分组。具体字段如下字段名说明示例Case ID全局唯一标识便于跨系统引用KC-REIMBURSEMENT-001模块功能模块知识库-报销查询标签可检索的标签集合RAG, Agent, 报销, 时间敏感前置条件环境/数据准备要求知识库已导入2025版报销政策测试步骤操作步骤1. 发起对话2. 输入“报销额度”预期结果期望行为返回2025版报销政策相关内容优先级P0/P1/P2P1维护人负责维护此用例的人张三构建Case Library的时候有两点经验可以分享按业务能力组织而不是按项目组织。同一个“报销查询”能力在不同项目里可能会被复用用例只维护一份各项目引用Case ID即可。打标签要克制。标签的目的是检索千万别什么都打我们只用了4个维度功能模块、技术特点RAG/Agent/接口/数据、业务领域、优先级。加太多反而难以维护。4.3 迭代回归时怎么筛选用例Case Library建好之后迭代回归时的用例筛选就成了关键。我们的做法是每次迭代锁定时由测试负责人根据改动范围筛选关联用例规则很简单改到哪个模块就选有该模块标签的用例。涉及Agent工具调用就额外选“工具接口”标签下的测试用例。涉及知识库召回就选“RAG”和“时间敏感”标签下的用例。P0级用例每次迭代必须全部回归P1级抽样30%P2级只在版本发布前回归。这样筛选之后这期RAG优化的回归测试从原本预估的3天压缩到了1.5天而且没有遗漏核心场景。测试用例真正变成了资产而不是躺在某个文档里的摆设。5. 这期迭代我们用到的企业级AI落地材料5.1 本地部署知识库助手的架构要点讲完流程上的坑回到技术本身。这段时间有不少朋友问我“怎么在企业内网部署一个知识库助手”我把我们目前的架构整理了一下可以作为一份参考。核心组件分五层数据接入层支持本地文档导入、数据库对接、API接口对接。企业级场景下最常见的需求是接入内部Wiki、SharePoint、OA系统以及部门自己的文档目录。文档处理层格式解析PDF、Word、Markdown、文本切分、目录结构提取。切分策略很关键我们采用的是“按章节切分固定大小兜底”固定大小的chunk size设置为512字符overlap设为32字符。向量化层Embedding模型统一封装成服务支持批量向量化。目前用的模型是开源的bge系列中文效果不错部署成本也可控。检索层向量检索 关键词检索 Rerank。向量检索用的是Milvus关键词检索借助Lucene的能力Rerank阶段用交叉编码器。应用层Java后端服务封装API包括对话接口、文档管理接口、权限控制接口。权限这块特别重要企业级知识库必须按部门/角色控制文档可见性不同部门的人查不到彼此的数据。权限隔离是本地部署和企业级应用最核心的差异化能力。我们的做法是在文档入库时给每个切分后的chunk打上部门标签检索时在召回阶段根据当前用户所属部门过滤保证跨部门的数据不会被检索到。这个过滤逻辑在向量检索里面直接加filter条件完成效率上比检索完再过滤高很多。5.2 Java AI Agent平台的关键设计再说Agent部分。我们在做Agent平台时没有直接套用Python的LangChain或LangGraph而是基于Java生态自己搭了一套轻量级的Agent框架核心原因有两个一是企业内部现有的技术栈以Java为主维护成本低二是很多AI应用要对接内部的Java微服务用Java直接调工具链链路更短。目前平台的关键设计包括四块工具注册与发现通过注解定义Agent工具启动时自动扫描注册到工具中心。Function Calling协议封装兼容主流大模型的Function Calling格式统一封装成内部工具调用协议。任务编排引擎支持串行、并行、条件分支的Agent流程编排。可观测性模块记录每次Agent执行的调用链、token消耗、工具调用结果。工具注册的代码大概长这样AgentTool( name query_reimbursement_policy, description 查询报销政策文档支持时间敏感查询, parameters { AgentToolParam(name keyword, type String.class, description 查询关键词), AgentToolParam(name date, type String.class, description 政策生效日期格式yyyy-MM-dd) } ) public class ReimbursementPolicyTool implements AgentTool { Override public ToolResult execute(MapString, Object params) { String keyword (String) params.get(keyword); String date (String) params.get(date); // 调用知识库检索服务返回政策文档 } }我们本期迭代中把“报销政策查询”和“年假余额查询”两个工具接入了Agent平台。前者调知识库检索服务后者直连人事系统的数据接口。两个工具跑通之后内部员工可以直接在对话里问“我今年还有几天年假”Agent自动判断需要调用哪个工具然后返回结构化的结果。这个能力上线后内部反馈整体不错。5.3 这一期的实际改动清单这期迭代最终落地的改动梳理下来是这样知识库检索服务新增了Rerank模型的接口定义代码已合入主干但Feature Flag默认关闭下个迭代做完整的评测。Agent平台新增了报销政策查询工具已对接知识库服务并全量开放。新增了Agent调用链的日志记录方便排查“Agent选了错误的工具”这类问题。测试用例库完成了第一批整理共收纳892条核心用例覆盖知识库、Agent、数据服务三个方向。资源审批后置任务清单机制上线目前正在积累监控数据。6. 我的几点真实体感6.1 需求“写进去”没那么难难的是“资源确认”这次迭代让我最深的体感是排期评审不是一个文档的终点而是一个资源确认的起点。一份方案哪怕写得再完善如果没有人、没有环境、没有数据源权限它就只是一个很好的PPT。所以现在每次排期我会拉着产品经理把资源清单逐项过确认每一项都已经申请且状态正常才把需求放进迭代承诺。资源不到位宁可不要这个需求否则挤占核心需求的资源两个都做不成。6.2 审批“批完”也没那么难难的是“下一个环节”审批系统的“已通过”只是流程环节的结束不是交付的结束。如果企业里审批之后还有人工交付环节一定要把后置环节的跟踪机制补上。我们在做过这件事之后才真正意识到大量跨团队协作的时间黑洞都发生在“节点交接处”——上一个环节的人觉得已经完成了下一个环节的人还不知道自己该干活。6.3 这个内容后面还能怎么扩展这期其实只是摸着石头过河的第一步。后续有几个方向我们已经在规划一是把测试用例库和自动化回归脚本打通做到标签选完用例之后直接触发对应的自动化测试任务二是把资源审批的看板做成一个正式的内部小工具挂到团队页面上替代现在的Python脚本电子表格方案三是RAG的Rerank评测做完之后如果效果符合预期会把完全体的混合检索方案铺开到时候再写一篇单点的技术细节分享。最后再分享一个小技巧如果你也在做企业级AI项目遇到“推进不下去”的时候先别急着归咎于技术难度先画一条从“提出需求”到“真正生效”的完整链路图把每一段的责任人和状态都标出来你会惊讶地发现大部分时间黑洞都不在技术研发本身而在流程交接的缝隙里。把这些缝隙补上你的迭代速度至少能快30%而且团队士气也会回来。
