企业官网建设流程全解析

1. 为什么要把十几个免费模型通道塞进一个入口

手里攒了一堆免费模型通道的人，大概都经历过这种混乱：写代码的时候想用响应快的，写文案的时候想用文笔好的，做长文档总结的时候又想换一个上下文窗口大的。结果就是浏览器里开着五六个标签页，每个平台一套账号体系，每次切换都要重新粘贴一遍提示词，一天下来光在窗口之间倒腾就耗掉不少精力。

WorkBuddy 这个工具解决的正是这个痛点。它的核心思路很朴素：把多个免费模型通道统一收拢到一个本地网关后面，对外只暴露一个入口，内部根据任务类型自动把请求路由到最合适的那个通道上。你不需要记住哪个通道对应哪个模型，也不需要手动切换，只需要把任务描述清楚，剩下的交给路由规则。

这里说的“14 个免费通道”并不是一个固定数字，而是一种典型配置规模。实际搭建时你可以接三个、五个，也可以接十几个，取决于你手头能稳定拿到的通道数量。关键在于 WorkBuddy 提供了一套基于models.json的配置机制，让你用声明式的方式把每个通道的能力标签、优先级、限流参数写清楚，路由层再根据这些元数据做决策。

适合读这篇内容的人有三类：一是手头有多个模型通道、被切换折磨得够呛的开发者；二是想给自己团队搭一个统一模型入口的技术负责人；三是单纯想搞清楚“自动路由”这件事在工程上到底怎么落地的好奇者。不管你属于哪一类，下面这些从实际搭建中攒下来的经验应该都能用得上。

需要先说明一点：本文讨论的是本地网关层面的路由与聚合，所有通道均指公开可用的模型服务接口，搭建过程完全在本地环境完成，不涉及任何网络穿透类工具。这一点在后面讲配置的时候还会反复提到，因为它直接决定了你的架构该怎么设计。

2. 拆解 WorkBuddy 的本地网关架构与路由决策链路

2.1 一个请求从进入到返回，中间到底经过了什么

很多人以为“自动路由”就是写个 if-else，判断一下任务类型然后转发。真搭起来会发现远不止这么简单。一个完整的请求链路至少包含五层处理：接入层负责接收请求并做基础校验；意图识别层判断这个请求属于哪类任务；路由决策层根据意图和通道状态选出目标通道；适配层把统一的请求格式转换成目标通道要求的格式；最后是响应处理层，把结果归一化后返回给调用方。

WorkBuddy 把这五层做成了一个轻量级的本地服务。接入层默认监听本地回环地址上的一个端口，你可以在配置文件里改。意图识别层用的是关键词加权加轻量分类的组合策略，不依赖外部服务，纯本地计算，所以延迟很低。路由决策层是整套机制的核心，它维护着一张通道能力表，每个通道标注了擅长的任务类型、当前健康状态、剩余配额和平均响应时间。

适配层这块值得多说两句。不同通道的接口协议、参数命名、返回结构都不一样，有的用messages数组，有的用prompt字符串，有的返回choices[0].text，有的返回content字段。WorkBuddy 在内部定义了一套统一的请求响应模型，适配层负责双向转换。你新增一个通道时，主要工作就是写一个适配器描述，告诉系统怎么把统一格式映射到该通道的格式。

响应处理层除了格式归一化，还做了一件事：记录每个通道的实际表现。每次请求的耗时、是否成功、返回质量评分（如果有的话）都会被写进本地的一个统计文件。这些数据反过来喂给路由决策层，让它在下次选择时能避开最近频繁出错的通道。这个反馈闭环是自动路由能越用越准的关键，也是很多人搭完网关后忽略的一步。

2.2 models.json 里每个字段背后的设计意图

models.json是整个路由机制的大脑，它的结构设计直接决定了路由的灵活度。一个典型的通道配置包含这些字段：

{ "channels": [ { "id": "channel-a", "endpoint": "http://127.0.0.1:8081/v1/chat", "model": "general-large", "capabilities": ["code", "reasoning", "long-context"], "priority": 1, "maxContextTokens": 128000, "rateLimit": { "rpm": 20, "concurrent": 3 }, "healthCheck": "/v1/models", "timeoutMs": 30000 } ] }

capabilities字段是路由决策的第一依据。它用标签的方式描述这个通道擅长什么，路由层拿到任务意图后，先做标签匹配，筛出候选通道集合。标签的粒度需要你自己把握：太粗了区分度不够，太细了维护成本高。我的经验是控制在六到八个标签以内，覆盖代码、推理、长文本、创意写作、翻译、总结、对话、结构化输出这几类就够了。

priority字段决定同能力通道之间的排序。数字越小优先级越高。但注意，优先级不是绝对的，它只在候选通道的能力标签都匹配时起作用。如果高优先级通道当前触发了限流或者健康检查失败，路由层会自动降级到下一个。这个降级逻辑是内置的，不需要你额外配置。

rateLimit里的rpm和concurrent两个参数必须认真填。填大了会导致通道被限流甚至临时封禁，填小了浪费通道能力。我的做法是先按通道官方文档给的理论值打个七折，跑一周后看统计文件里的实际触发情况再微调。concurrent尤其要注意，很多免费通道对并发连接数卡得很死，超过就直接拒绝，所以宁可保守一点。

healthCheck字段指定一个轻量级的探测路径，WorkBuddy 会按固定间隔去请求这个路径，根据返回状态更新通道的健康标记。这个探测频率不要设太高，否则健康检查本身就会消耗掉不少配额。我一般设成五分钟一次，对于稳定性较差的通道可以缩短到两分钟。

2.3 意图识别为什么不用大模型来做

这是个容易被问到的设计问题：既然手头有这么多模型通道，为什么意图识别不直接调一个模型来判断？答案很简单——成本和延迟。意图识别发生在每次请求的最前端，如果这一步就要调模型，那整个链路的延迟至少增加几百毫秒，而且会消耗掉一次模型调用配额。对于高频使用的场景，这笔开销累积起来很可观。

WorkBuddy 采用的是一种混合策略：先用规则做快速分流，规则覆盖不到的情况再用一个极轻量的本地分类器。规则部分主要看请求里的几个信号：系统提示词里有没有出现代码相关的关键词、用户消息的长度分布、是否包含结构化输出的格式要求、有没有明确指定任务类型。这些信号加权求和后落到某个意图类别上，整个过程在毫秒级完成。

本地分类器是一个小型的文本分类模型，参数量很小，跑在本地 CPU 上就够。它的训练数据来自你历史请求的标注结果——每次路由完成后，系统会记录实际使用的通道和任务的实际表现，这些数据积累到一定量就可以用来微调分类器。换句话说，这套意图识别是越用越准的，前提是你愿意花时间做数据积累。

规则和分类器的分工比例大概是七三开。规则处理那些特征明显的请求，分类器兜底处理模糊地带的请求。这个比例不是固定的，你可以通过配置文件调整两者的权重。如果你的使用场景比较固定，规则覆盖率高，可以把分类器权重调低甚至关掉，进一步降低延迟。

3. 从零搭建：通道接入、配置编写与首次联调

3.1 环境准备阶段最容易忽略的三件事

搭建之前先把环境理清楚，能省掉后面很多返工。第一件事是确认本地端口占用情况。WorkBuddy 默认用 127.0.0.1 上的一个端口做网关监听，如果你机器上已经有其他服务占着这个端口，启动时会直接报错。建议提前用netstat或者lsof查一遍，把要用的端口段规划好。我一般会预留连续五个端口，网关一个、健康检查一个、统计接口一个，剩下两个备用。

第二件事是确定配置文件的存放位置。models.json默认放在工作目录下，但如果你用 Docker 跑，就要注意挂载路径的映射关系。很多人第一次跑 Docker 版本时发现配置改了不生效，八成是挂载路径写错了，容器里读的还是镜像内的默认配置。我的习惯是在宿主机上建一个专门的配置目录，启动时用-v参数把这个目录挂到容器内的配置路径上，这样改配置不用重新构建镜像。

第三件事是日志目录的权限。WorkBuddy 会把运行日志和统计文件写到本地磁盘，如果目录没有写权限，服务启动后会在第一次写日志时静默失败，表现就是“服务好像起来了但什么都没记录”。这个问题排查起来很费时间，因为服务本身不报错。建议启动前先手动确认一下日志目录的读写权限，Windows 下注意不要放在需要管理员权限的系统目录里。

提示：如果你在 Windows 7 这类较老的系统上部署，注意检查运行环境依赖是否齐全。部分新版本的运行时在旧系统上会有兼容性问题，建议优先使用官方文档中标注支持的系统版本。

3.2 把第一个通道接进来并跑通一次完整请求

环境就绪后，先别急着把十几个通道全配上。我的建议是先用一个通道跑通全链路，确认接入层、路由层、适配层、响应层都正常工作，再批量加通道。这样出问题时排查范围小，定位快。

第一步，在models.json里写一个最简通道配置。只填必填字段：id、endpoint、model、capabilities。其他字段先用默认值。capabilities先随便填一个标签，比如general，等跑通后再细化。

第二步，启动 WorkBuddy 服务。观察启动日志，确认它读取到了配置文件，并且成功加载了通道。如果日志里出现“channel loaded”之类的字样，说明配置解析没问题。如果报解析错误，多半是 JSON 格式问题，用在线校验工具过一遍。

第三步，发一个测试请求。用 curl 或者 Postman 向网关地址发一个最简单的对话请求，请求体里只放一句“你好”。观察返回结果，同时看日志里路由决策的记录。正常情况下，日志会显示意图识别结果、候选通道列表、最终选中的通道、请求耗时。

第四步，验证适配层转换是否正确。这一步容易被跳过，但很重要。你可以在配置里打开调试模式，让 WorkBuddy 把转换前后的请求体都打印出来。对比一下统一格式和目标通道格式的差异，确认字段映射没有遗漏。我遇到过因为适配器里少映射了一个参数导致返回结果被截断的情况，排查了半天才发现是适配层的问题。

跑通这一个通道后，你对整套机制的理解会清晰很多。接下来加通道就是重复劳动，把每个通道的配置按同样的结构写进去，填好各自的能力标签和限流参数。

3.3 批量接入时的配置组织技巧

通道数量上去之后，models.json会变得很长，维护起来容易出错。几个实用的组织技巧：把通道按能力分组，同一组的配置放在一起，组间用注释分隔。JSON 本身不支持注释，但 WorkBuddy 的配置解析器兼容 JSONC 格式，允许写//注释。这个特性在维护多通道配置时非常有用。

另一个技巧是把敏感信息抽出来。虽然免费通道大多不需要密钥，但有些通道可能需要一个标识或者 token。这些信息不要直接写在models.json里，而是通过环境变量注入。WorkBuddy 支持在配置值里用${ENV_VAR}的语法引用环境变量，启动时自动替换。这样配置文件可以安全地纳入版本管理，不用担心泄露问题。

还有一个经验是给每个通道加一个notes字段，写清楚这个通道的来源、申请时间、已知限制。这个字段不参与路由决策，纯粹是给人看的。过几个月回头看配置时，你会感谢当时写了备注的自己。我现在的配置里每个通道都有备注，包括“这个通道高峰期响应慢”“这个通道对长文本支持不好”之类的实战观察。

批量接入后一定要做一轮全通道健康检查。WorkBuddy 提供了一个命令行工具，可以遍历所有配置的通道逐个发探测请求，输出每个通道的可用状态和响应时间。这个检查建议在每次修改配置后都跑一遍，确保没有通道因为配置错误而失效。

4. 路由策略调优：让任务落到真正合适的通道上

4.1 能力标签体系怎么设计才不鸡肋

能力标签是路由决策的基石，设计得好，路由准确率能到九成以上；设计得不好，标签形同虚设，最后还是靠人工切换。我踩过的坑是一开始标签设得太细，搞了二十多个标签，结果每个通道都要打一堆标签，维护成本极高，而且很多标签之间界限模糊，路由时经常出现多个通道同时匹配的情况。

后来我把标签体系收敛到八个核心标签，每个标签有明确的判定标准：

这八个标签基本覆盖了日常使用的绝大多数场景。每个通道根据自己的实际能力打上对应的标签，一般一个通道打三到五个标签。打标签的依据不能靠猜，要实际测试。我的做法是给每个通道准备一组标准测试用例，每个标签对应两三个用例，跑一遍看通过率，通过率高的才打上对应标签。

标签匹配的优先级也要考虑。一个请求可能同时命中多个标签，比如“把这段代码翻译成 Python”同时命中 code 和 translate。这时候路由层会按标签的权重排序，权重高的标签优先匹配。权重可以在配置里调，默认情况下 code 和 reasoning 的权重最高，因为它们对模型能力的要求最苛刻。

4.2 限流与降级：通道挂了之后请求去哪了

免费通道最大的不确定性就是稳定性。今天能用的通道明天可能就限流了，或者响应时间突然从两秒变成二十秒。路由层必须有一套完整的降级机制，否则一个通道出问题就会拖垮整个入口。

WorkBuddy 的降级逻辑分三个层次。第一层是健康检查失败降级：如果某个通道连续三次健康检查不通过，它会被标记为不可用，路由时直接跳过。这个标记有自动恢复机制，健康检查恢复正常后会自动重新纳入候选。第二层是限流降级：当通道返回限流错误码时，路由层会把这个通道临时移出候选池，冷却一段时间后再放回来。冷却时间可以配置，我一般设成六十秒。第三层是超时降级：请求发出后超过配置的超时时间还没返回，路由层会中断这次请求并切换到下一个候选通道重试。

这三层降级是叠加生效的。一个通道可能同时触发健康检查失败和限流，那它会被双重标记，恢复条件也更严格。实际运行中，我观察到大部分降级都是第二层限流触发的，因为免费通道的配额普遍偏紧。

降级之后请求去哪了？路由层会从候选通道列表里按优先级顺序找下一个可用的。如果所有候选都不可用，会返回一个明确的错误信息，而不是无限等待。这个错误信息里会包含每个候选通道的不可用原因，方便你排查是哪个通道拖了后腿。

注意：降级重试会消耗额外的配额。如果一个请求在三个通道上都重试了一遍，那就消耗了三次调用。所以在配置超时时间时要权衡：设太短会导致频繁重试浪费配额，设太长会让用户等待过久。我的经验值是普通任务设十五秒，长文本任务设三十秒。

4.3 用统计反馈让路由越跑越准

路由策略不是配好就一劳永逸的，它需要根据实际运行数据持续调整。WorkBuddy 会把每次请求的详细信息写进统计文件，包括时间戳、意图类别、候选通道、选中通道、响应耗时、是否成功、是否触发降级。这些数据是调优的依据。

我每周会花十分钟看一遍统计报告，重点关注三个指标：各通道的成功率、各意图类别的平均响应时间、降级触发频率。成功率低于八成的通道要考虑是不是标签打错了或者通道本身不稳定。某个意图类别的响应时间明显偏高，说明路由可能选错了通道，需要调整标签权重。降级频率突然升高，通常是某个通道的配额用完了或者服务出了状况。

统计报告里还有一个有用的数据是“通道切换率”，指的是同一个意图类别下，实际选中的通道分布情况。如果某个意图类别总是落到同一个通道上，说明其他通道的标签可能没打对，或者优先级设置不合理。理想情况下，同一意图类别应该有两到三个通道轮流承接，这样单个通道出问题时影响面小。

基于统计数据做调整时，建议一次只改一个变量，改完观察几天再决定下一步。同时改多个参数会导致你分不清是哪个改动起了作用。我一般周一调整配置，观察一周，下周一再看数据决定是否继续调。这个节奏虽然慢，但每一步都踩得实。

5. 实战中踩过的坑与对应解法

5.1 请求格式转换丢失字段的排查过程

适配层转换丢字段这个问题，我遇到过两次，每次表现都不一样，排查思路值得记录一下。第一次是返回结果被截断，明明通道返回了完整内容，但网关返回给调用方的只有前半段。排查时先看了通道的原始返回，确认内容是完整的，然后看网关的响应处理日志，发现归一化后的内容确实变短了。问题出在适配器的响应映射上，某个字段的路径写错了，导致只取到了部分内容。

第二次是请求参数丢失，发给通道的请求里少了一个控制输出长度的参数，导致通道按默认值返回了很长的内容。这次排查更麻烦，因为请求发出去了，但参数没带上。最后是在调试模式打印的转换前后请求体对比里发现的，统一格式里有这个参数，但适配器的请求映射里漏掉了。

这两次踩坑之后，我养成了一个习惯：每接入一个新通道，先做一轮字段映射的对照测试。准备一个包含所有统一格式字段的测试请求，发出去后对比通道实际收到的请求和实际返回的响应，逐字段核对。这个测试花不了几分钟，但能避免后面大量的排查时间。

WorkBuddy 的调试模式在这类排查中非常关键。打开调试模式后，它会把每个请求的原始格式、转换后格式、通道返回原始格式、归一化后格式都写到日志里。四个格式放在一起对比，字段丢失的问题一目了然。建议在接入新通道的阶段始终开着调试模式，稳定运行一周后再关掉。

5.2 并发配置不当导致的连锁限流

并发数配置这个坑，我踩得比较惨。一开始给每个通道都设了比较高的并发数，想着能提高吞吐。结果运行了不到半小时，多个通道同时开始返回限流错误，整个网关的可用性骤降。排查后发现，问题不在于单个通道的并发设高了，而在于多个通道共享了同一个上游配额池。

有些免费通道虽然接口地址不同，但背后是同一套配额系统。你在这边设了三个并发，那边设了五个并发，加起来八个并发全打到同一个配额池上，自然就超了。这个信息在通道的官方文档里通常不会写，只能通过实际运行观察。

我的解法是给通道配置加一个quotaGroup字段，把共享配额池的通道归到同一组，路由层在计算并发时会按组汇总，而不是按单个通道计算。这个字段不是 WorkBuddy 的内置功能，是我在适配层里加的一个扩展。如果你也遇到类似情况，可以考虑在路由决策前加一层配额组检查。

另一个相关的问题是并发数的动态调整。固定并发数在流量波动大的场景下不够灵活。我后来改成根据通道的实时响应时间动态调整：响应时间短就适当提高并发，响应时间变长就降低并发。这个逻辑也是加在适配层里的，WorkBuddy 本身提供了钩子函数，允许你在路由决策前后插入自定义逻辑。

5.3 缓存目录位置引发的启动异常

缓存目录这个问题，在 Windows 上尤其容易遇到。WorkBuddy 默认把缓存和临时文件放在系统临时目录下，但有些系统的临时目录权限设置比较严格，或者磁盘空间不足，导致服务启动时写缓存失败。表现是服务进程起来了，但第一次处理请求时就崩溃。

排查这个问题的关键是看启动日志里的缓存初始化部分。如果日志里出现“cache directory not writable”之类的提示，那就是缓存目录的问题。解法很简单，在配置里显式指定一个缓存目录，指向一个有写权限且空间充足的位置。我一般会在工作目录下建一个cache子目录，专门给 WorkBuddy 用。

Linux 下这个问题相对少见，但如果你用 Docker 跑，要注意容器内的缓存目录和宿主机的映射关系。容器重启后容器内的缓存会丢失，如果缓存目录没有挂载到宿主机，每次重启都要重新预热缓存，影响启动后的首批请求性能。建议把缓存目录也挂载出来，和配置目录放在一起管理。

还有一个细节是缓存清理策略。WorkBuddy 默认的缓存过期时间是二十四小时，对于高频使用的场景，这个时间可能太长，缓存文件会积累得很大。可以在配置里把过期时间调短，比如设成六小时。同时建议加一个定时清理任务，每天凌晨清理一次过期缓存，避免磁盘被占满。

6. 把 WorkBuddy 用顺手的几个进阶习惯

6.1 给常用任务预设路由规则

自动路由虽然方便，但对于一些高频且固定的任务，预设规则比自动判断更可靠。WorkBuddy 支持在配置里写路由规则，格式是“当请求满足某条件时，强制走某个通道”。比如你可以设一条规则：所有包含“翻译”关键词的请求都走翻译能力最强的那个通道，不参与自动路由的竞争。

预设规则的优先级高于自动路由。当一条请求同时满足多条规则时，按规则的定义顺序匹配，第一条匹配上的生效。所以规则的顺序很重要，要把最具体的规则放在前面，最宽泛的放在后面。我一般会把规则分成三组：精确匹配组、关键词匹配组、兜底组，按这个顺序排列。

规则不是越多越好。规则太多会削弱自动路由的价值，而且维护成本高。我的经验是控制在十条以内，只给那些“自动路由经常选错”或者“对结果质量要求特别高”的任务设规则。其他任务交给自动路由，让它自己学习和调整。

规则配置里还可以指定降级通道。比如某条规则指定走通道 A，但通道 A 不可用时，可以指定降级到通道 B 而不是回到自动路由。这个设置对于有明确质量要求的任务很有用，避免降级后落到一个完全不合适的通道上。

6.2 多设备同步配置的注意事项

如果你在多台设备上都用 WorkBuddy，配置同步是个绕不开的问题。最直接的做法是把models.json和缓存目录放在同步盘里，多台设备共享同一份配置。但这样做有个隐患：不同设备的网络环境不同，同一个通道在 A 设备上能用，在 B 设备上可能因为网络策略访问不了。

我的做法是配置分两层：基础配置放同步盘，包含通道的通用信息和能力标签；设备特定配置放本地，包含该设备上实际可用的通道列表和网络相关的参数。WorkBuddy 启动时会合并这两层配置，本地配置覆盖基础配置里的同名字段。这样既能共享大部分配置，又能适配每台设备的实际情况。

同步配置时还要注意版本一致性。不同设备上的 WorkBuddy 版本可能不同，新版本支持的配置字段在旧版本上会被忽略，导致行为不一致。建议在同步盘里放一个版本说明文件，记录当前配置对应的 WorkBuddy 版本，升级时同步更新。我吃过这个亏，在一台设备上加了新字段，另一台设备上没生效，排查了半天才发现是版本差异。

6.3 安全审核与日志脱敏的实操建议

本地网关虽然不对外暴露，但日志里可能会记录请求内容，如果请求里包含敏感信息，日志就成了泄露渠道。WorkBuddy 提供了日志脱敏功能，可以在配置里指定需要脱敏的字段和脱敏规则。建议把用户消息内容、系统提示词里的敏感部分都纳入脱敏范围。

脱敏规则支持正则表达式，可以精确匹配需要处理的内容。比如你可以设一条规则，把所有符合某种格式的字符串替换成占位符。脱敏发生在日志写入之前，不影响实际的请求处理。这个功能在多人共用网关的场景下尤其重要，避免一个人的请求内容被另一个人的日志看到。

除了日志脱敏，还建议定期做安全审核。审核内容包括：配置文件里有没有硬编码的敏感信息、日志目录的访问权限是否合理、网关监听的地址是不是只绑定了本地回环、有没有意外的外部访问记录。这几项检查每个月做一次，花不了多少时间，但能避免很多潜在问题。

提示：网关监听地址务必设置为本地回环地址，不要绑定到对外网卡上。如果确实需要局域网内其他设备访问，建议在前端加一层访问控制，而不是直接把网关暴露出去。

6.4 从入门到精通的路径建议

最后聊聊学习路径。WorkBuddy 这类工具的上手曲线其实不陡，但要用得精，需要分阶段推进。第一阶段是跑通单通道，理解请求从进入到返回的完整链路，这个阶段大概花一两个小时。第二阶段是接入三到五个通道，把能力标签和限流参数配好，跑一周观察统计数据，这个阶段大概花一个周末。第三阶段是根据统计数据调优路由策略，加预设规则，处理降级和并发问题，这个阶段是持续进行的，没有明确的终点。

我见过很多人卡在第二阶段，通道接进来了但没耐心看统计数据，路由策略一直用默认值，结果自动路由的效果还不如手动切换。自动路由的价值在于持续调优，它不是一个开箱即用的魔法，而是一个需要你投入时间喂养的系统。你给它的反馈数据越多，它的决策就越准。

如果你想把 WorkBuddy 用到团队场景，建议先在小范围试点，选两三个高频任务类型，跑两周看效果。效果稳定后再推广到更多任务类型和更多成员。推广过程中注意收集使用反馈，特别是“路由选错通道”的案例，这些案例是调优的宝贵输入。我在团队里推的时候，专门建了一个反馈文档，大家遇到路由不合理的请求就记一笔，每周汇总分析一次，两个月下来路由准确率提升很明显。

这套东西搭起来之后，最大的感受是“入口统一”带来的心智负担降低。以前要在多个平台之间切换，脑子里得记着哪个平台擅长什么、哪个平台今天额度用完了。现在只需要把任务描述清楚，剩下的交给路由层。这种从“人适应工具”到“工具适应人”的转变，才是自动路由真正的价值所在。