那个周五晚上之前我从没想过一个“返回码0”的搜索接口能把模型的答案带偏到沟里去。日志里明明白白写着search web exit 0结果却是空结果。模型读到这个结果非常自信地告诉用户“当前没有相关实时信息”——但我手动打开网页搜索明明排满了一整页。问题不在搜索引擎也不在模型在我自己搭的这套“把联网检索从模型里拆出来”的组件上。也就是标题里的这个bl search web。这篇文章想把整条链路拆开讲清楚为什么要拆、拆完后的三层结构怎么分工、退出码怎么设计才能让模型准确读到状态以及我在真实运行里踩到的两个静默坑——它们有一个共同点程序本身没报错退出码是0但结果已经是错的。这类问题最难排查也最值得写下来。1. 先说说为什么要拆模型内置检索的三个硬伤我在做检索增强类的Agent项目时最初图省事直接让模型自己带联网检索能力。模型厂商标榜的“内置搜索”确实方便一行配置就能用。但真跑起来我撞上了三个绕不开的问题。第一个是输出格式不可控。模型内置搜索返回的是大段自然语言什么“根据最新报道……”“多个来源显示……”摘要密度低、废话多几轮对话下来上下文Token消耗很猛。而且不同的模型厂商返回格式各不相同接口返回的字段、关键信息的位置都不一样代码里想统一解析非常痛苦。我们当时的做法是为每家厂商单独写解析逻辑维护成本直线上升。第二个是切换模型代价大。只要换一个主流模型搜索能力就跟大便。之前内置搜索的可用性、返回稳定性全废得重新适配。项目里的核心逻辑倒是没变变的全是“模型怎么调用搜索”这一层架构被模型厂商绑架了。第三个是无法精细化控制检索策略。模型内置的搜索往往是黑盒不知道它搜了几个源、用的什么排序、超时多久、有没有重试、有没有反爬兜底。想限定“只搜学术源”“有时间截止”这类业务规则根本做不到。对于生产系统来说不可控就是不可用。所以我决定把这块拆出来做成一个独立模块也就是bl search web这个CLI工具。模块只负责一件事接收“检索词 若干选项”输出“结构化结果或明确的失败状态”。模型不再自己搜索而是通过工具调用这个模块就像调用一个普通函数。拆完之后收益很明显不同模型都能复用它适配某个新模型时不用重写搜索层搜索策略集中在一处调参和排障都能在一处完成最关键的搜索成功和失败变成了一种可编程判别的状态而不是模型自由发挥的自然语言。2. bl search web 的三层职责接入层、编排层、执行层很多人在做这类工具时犯的错误是只写了一个“搜索函数”把所有逻辑堆在一起。bl search web能稳健运行核心是内部逻辑按职责拆成了三层。每一层只干一件事而且对上层暴露的接口是稳定的。2.1 接入层模型只认这份协议接入层是模型真正接触的地方。它可以是CLI命令、HTTP接口也可以是函数调用里的一个tool定义。我在项目里用的是CLI方式因为命令行接口最容易被各种Agent框架包装也最容易手动调试。这一层要做的事只有三件解析参数、调用编排层、按约定格式化输出。输出内容分两路stdout走干净的结构化字段这是给模型看的stderr走详细日志这是给人排查用的。模型侧永远只读stdout程序侧永远检查退出码。2.2 编排层查询路由、并发与超时策略编排层是所有策略的聚集地选哪个搜索源、多个源是串行还是并发、超时多久、结果按什么排序、最多返回几条、失败要不要降级。这一层相当于调度中心它自己不直接做网络请求。例如我这里的策略默认并发请求两个独立搜索源谁先回来且质量达标就用谁超过4秒就放弃慢的那一个如果两个都失败不自动降级而是把失败状态原样抛回接入层。这个“失败不降级”的原则正是后面两个静默坑的关键教训——宁可让上层知道自己失败也不要伪造一个“空结果”。2.3 执行层搜索源适配器如何隔离变化执行层是最动荡的一层每个搜索源一个适配器。各家的页面结构、反爬策略、返回格式都可能随时变化如果没有隔离任何一个小变动都会炸到上层。我的做法是让每个Provider实现同一个接口# provider.py from dataclasses import dataclass, field dataclass class SearchResult: title: str url: str snippet: str source: str rank: int class BaseProvider: name: str base def search(self, query: str, timeout: float 5.0, max_results: int 5) - list[SearchResult]: raise NotImplementedError def parse(self, raw_html: str) - list[SearchResult]: raise NotImplementedErrorProvider.search负责发起实际请求Provider.parse负责解析页面。两层拆开是为了让“网络请求异常”和“页面结构异常”能分别处理。任何一个新搜索源接入时我只需要实现这两个方法然后注册到编排层别的都不用动。这也是整个模块能长期稳定运行的结构基础。3. 退出码是真正的“模型协议”stdout才是给人看的工具拆出来后我发现最容易被低估的是退出码设计。模型读工具返回值时通常只看stdout里的自然语言。但问题是自然语言是有歧义的。举两个例子。Tool返回“没有找到相关信息”这到底是正常空结果还是搜索失败了模型分不清。Tool返回“发生错误”模型可能觉得“这是结果不是错误”然后就拿这句话去回答了。所以必须有一个模型能读懂的程序化信号这就是退出码。3.1 一个足够细的退出码表bl search web的退出码不是标准Unix那种简单的0/1而是按“模型需要如何应对”来设计的退出码含义模型应做出的反应典型来源0搜索成功返回了有效结果正常使用结果正常解析出条目1参数错误检查调用参数不要重试缺少query、非法选项2请求超时可以稍后重试或换关键词重试上游响应超时3正常空结果修改检索词或采用其他策略搜词太偏、无匹配4疑似被拦截/反爬换搜索源或放慢频率别直接硬刚出现验证页、跳转页5页面解析失败升级工具本身模型侧无需处理HTML结构变化设计哲学是每个非0退出码都对应一类“模型可以执行的决策”。0是成功1是使用方式问题2、4是临时的可以重试或换策略3是确定性的正常状态5说明工具该更新了。退出码表定下来后模型侧的工具调用代码就非常简单了。伪代码import subprocess import json def search_web(query: str) - str: proc subprocess.run( [bl, search, web, query, --format, json], capture_outputTrue, textTrue, timeout10 ) if proc.returncode 0: return proc.stdout elif proc.returncode 2: return [搜索超时稍后可重试] elif proc.returncode 3: return [确认无匹配结果请换关键词] elif proc.returncode 4: return [搜索被拦截建议换时间或换源] else: return f[搜索失败退出码 {proc.returncode}请稍后重试]3.2 怎么把退出码接进大模型工具调用主流的Agent框架都支持“工具返回错误信息后由模型自行决定下一步”。问题在于框架传给模型的往往是stdout文本退出码并不直接被模型看见。所以我的做法是把退出码的语义翻译成一句简短的状态描述拼在返回内容最前面。模型先看到状态句再看到真实内容决策质量高很多。真实运行中还有一个细节超时处理。subprocess.run内部的timeout参数必须比所有Provider的总超时预留得多否则会抛出TimeoutExpired工具中断模型拿到的不是任何可识别的状态而是一段半截输出。我后来统一在接入层捕获这类异常把它转成“搜索超时”的状态句才能进得了模型上下文。4. 静默坑之一验证页被当成正常结果返回模型照单全收4.1 事故重现返回码0、内容离谱那是某次凌晨的批量任务我查看日志看到一大片奇怪的记录。退出码都是0stdout里确实有title、snippet字段看起来完全正常。但我点开结果里的url一看页面标题是“安全验证”snippet是“请完成以下验证码以继续访问”。显然这是某个搜索源在深夜触发了反爬拦截返回了一个验证页面。问题是解析器为什么会把它当结果返回4.2 排查链路从现象到根因我当时的排查路径是这样的。先看退出码全0毫无疑点。再看stdout有一条结果字段完整像是正常结果。然后用命令行单独跑了一次bl search web 测试关键词 --source SourceA --format json echo $?返回依然是0输出照样是一条“安全验证”的记录。接着抓原始响应。在Provider里临时用一个参数打印前2000字节的HTML发现响应的HTTP状态码是200但DOM结构和真正的搜索结果页完全不同——没有搜索结果容器取而代之的是验证脚本和跳转逻辑。根因就藏在解析逻辑里。原代码的思路是先尝试提取搜索结果容器提取不到时不抛错而是退化为“用页面标题 meta description 构造一条兜底结果”。设计这个兜底的初衷是怕某一次搜索结果为空时让模型一无所获结果却成了静默失败的温床。页面标题和meta description在验证页上一样存在于是解析器愉快地构造了一条“结果”而且没有显式标记这是一条低置信度结果。4.3 修复方案与回归用例修复分三步走。第一步删除“构造兜底结果”的逻辑搜索容器不存在时直接抛出不可解析异常。第二步在编排层把这类异常映射为退出码4。第三步增加对典型关键词的过滤比如snippet或title里出现“验证码”“安全验证”“滑动解锁”等特征时跳过该来源并让编排层重试其他源。回归用例是事后必须补的。我给解析器写了三个测试样本正常搜索页、验证页面、只有空容器的页面。断言分别是正常页提取到N条结果、验证页抛异常、空容器抛异常。以后再遇上搜索源改版跑一遍测试就能看出是哪类问题。这个坑的教训我总结成一句话与其返回一条“可能不对”的结果不如明确告诉模型“我没拿到有效结果原因可能是被拦截”。模型处理“明确失败”的能力远比处理“看似成功实则垃圾”强。5. 静默坑之二超时被默认值吞掉失败被伪装成“无结果”5.1 事故重现搜索有结果模型却说没有第二个坑更隐蔽。某天线上反馈Agent在回答“今天有什么热点的实时消息”时模型回复“暂无最新相关信息”。我手动检查搜索源结果正常内容绝对可以搜到。查日志bl search web返回的是退出码0、total0也就是“正常空结果”。不论怎么看程序都没有异常。但我觉得不对劲。于是把搜索引擎的实际请求时间临时打印出来发现SourceA响应稳定在7到9秒之间而编排层的并发超时设置是8秒——上游稍微一震请求就来不及返回了。5.2 根因通用的裸捕获把状态抹掉了顺着代码往下翻看到了罪魁祸首try: future pool.submit(provider.search, query, timeout5.0) results future.result(timeout8) except Exception: results [] # 任何异常一律返回空列表一行except Exception把TimeoutError、ConnectionError、ParseError全部吞掉统一变成空列表。上层看到空列表就把total记成0退出码定为0成功但无结果。于是“搜索失败”被静默地替换成“没有搜索结果”模型接收到的是完全错误的语义。为什么一开始没发现因为通常在正常网络下请求2秒内就能返回超时是小概率事件。只在网络波动或目标站点变慢时才会触发。而这种场景恰恰发生在用户最需要实时信息的时候影响被放大了。5.3 修复与验证修改思路有两条。第一条不允许“异常变成空列表”这种静默降级异常处理必须显式区分类型try: results future.result(timeout8) except TimeoutError: raise SearchTimeoutError(fsource{provider.name} 8s timeout) except Exception as e: raise SearchFailedError(fsource{provider.name} failed: {e})TimeoutError统一转成退出码2可重试其他网络异常转成退出码5或对应类型。第二条是编排层加了一个“耗时审计”日志把每个Provider的耗时、状态、结果条数都打出来。事后排障时能一眼看出“是超时了还是真的没结果”。验证环节我引入了一个故障注入参数可以人为给Provider加几秒延迟触发超时路径确认退出码确实是2、stderr有耗时信息、模型侧收到的状态句是“搜索超时”而不是“空结果”。这类故障注入测试现在是我每次改动搜索模块必跑的用例。这里顺带也暴露了一个容易被忽略的设计倾向所有上层对象里那些带默认值的空集合空列表、空字典都要警惕。默认值本身没有错错的是异常路径里把“状态”丢掉了默认值就变成了替罪羊。6. 沉淀下来的经验与排查通用套路写完这两个坑我复盘了整个设计浓缩出三条对工具调用类项目都适用的经验。第一用结构化状态代替自然语言反馈。退出码、错误码、结构化字段这些程序化信号才是机器之间协作的可靠语言。模型再聪明也不能靠猜状态来决策。凡是“文本”能表达的状态都应该有对应的“程序状态”兜底。第二对“静默失败”零容忍。我后来给团队立了一条规矩宁可显式失败、退码非0也不要返回看起来正常但实际上残缺或错误的结果。因为显式失败模型知道要重试静默失败模型会用错误信息继续往下推理污染的是整个回答。第三把故障注入纳入日常测试。现在bl search web每次发版必须跑一遍故障注入用例超时、验证页、乱码、空容器、半截JSON全部都要过。这个方法对于任何涉及外部调用的模块都适用不局限于搜索。另外再分享一个个人习惯。现在排查工具类问题时我从来不会只看退出码和结果文本。我会先抓原始响应看“外部系统给我的到底是什么”然后才看自己的解析和状态映射。很多问题的根源都出在中间那层映射上而不是网络本身。bl search web这个模块拆出来之后最大的收获其实不是一次搜索快了0.3秒也不是某个模型换得飞快而是它把“搜索”从“模型行为”里彻底剥离出来变成了一块可以独立调试、独立测试、独立排障的组件。对于任何要长期维护的Agent系统这种边界感比任何优化都值钱。
