1. 为什么要把十几个免费模型通道塞进一个入口我最早用 WorkBuddy 的时候配置里塞了七八个免费模型的接入点每次切换任务都得手动改一遍配置写代码用一个、写文档换一个、做翻译再换一个一天下来光切模型就浪费不少时间。后来我把 14 个免费通道全部整合到一个本地网关里对外只暴露一个入口内部按任务类型自动路由效率直接翻倍。这套方案的核心思路就是用一层轻量路由把多个免费模型的差异屏蔽掉让调用方只关心任务本身不关心背后是谁在干活。先说清楚这套东西解决的是什么问题。免费模型通道有几个共性痛点一是每个通道的接口格式、鉴权方式、参数命名都不一样有的用 OpenAI 兼容格式有的自己搞一套二是免费额度有限单个通道跑不了几个请求就限流了三是不同模型擅长的任务不一样有的写代码强有的长文本处理好有的响应快但质量一般。如果每次都手动选根本忙不过来。所以需要一个中间层把这些差异全部吃掉对外提供统一的调用方式同时根据任务特征自动挑最合适的通道。适合谁来参考这套方案如果你手上有多个免费模型的接入权限又不想每次手动切换如果你在本地跑 WorkBuddy 或者类似的工作台工具想让它自动调用不同模型如果你对本地网关、路由分发这类东西感兴趣想自己搭一套玩玩那这篇内容就是写给你的。不需要多深的后端功底能看懂 JSON 配置、会跑简单的本地服务就行。我用的方案不依赖任何特定平台核心就是一个本地 HTTP 服务加一份路由配置表。WorkBuddy 那边只需要把模型接入地址指向本地网关剩下的路由逻辑全部在网关内部完成。下面我从整体设计开始拆把每个环节的考量和实操细节都讲透。2. 整体架构设计与路由思路拆解2.1 核心架构三层结构各管各的事整套方案分三层。最上层是 WorkBuddy 工作台它只认一个模型入口就是本地网关的地址。中间层是路由网关负责接收请求、判断任务类型、选择目标通道、转发请求、处理响应。最下层是 14 个免费模型通道每个通道有自己的接口地址和鉴权信息。这样分层的好处很明显。WorkBuddy 那边完全不用改它以为自己只连了一个模型。路由网关是独立进程改路由规则不用动 WorkBuddy 的配置。底层通道增减也不影响上层加一个新通道只需要在网关配置里加一条记录。我试过把路由逻辑直接写在 WorkBuddy 的配置里结果发现根本行不通因为 WorkBuddy 的模型配置不支持条件判断只能指定一个固定的接口地址。所以必须把路由逻辑外置用一个独立的服务来承担。2.2 路由策略按任务特征匹配不按模型名字硬编码路由的核心是判断这个请求该走哪个通道。我的做法不是简单轮询而是根据请求内容里的特征来匹配。具体来说看几个维度请求里有没有代码块或者代码相关的关键词、文本长度是多少、是不是翻译任务、是不是需要长上下文。举个例子如果请求里包含大量代码片段就优先路由到代码能力强的通道如果是长文档摘要就路由到上下文窗口大的通道如果是快速问答就路由到响应速度快的通道。这些判断逻辑全部写在网关的路由规则里用简单的关键词匹配和长度阈值就能实现不需要上机器学习那一套。为什么不用轮询因为轮询会导致代码任务被分配到不擅长代码的模型上输出质量直接下降。免费通道本来就参差不齐必须扬长避短。我实测下来按任务特征路由比轮询的可用率高出不少尤其是代码类任务匹配对了通道之后基本一次就能用。2.3 容错设计一个通道挂了自动切下一个免费通道最大的问题是不稳定随时可能限流或者超时。所以路由网关必须带容错。我的做法是每个任务类型配置一个主通道和两个备用通道主通道请求失败或者超时自动切到备用通道重试。重试次数限制在两次以内避免无限循环。这里有个细节要注意切换通道之后请求格式可能需要转换。比如主通道用 OpenAI 格式备用通道用另一种格式网关内部要做格式适配。我在网关里加了一层格式转换模块把统一格式的请求转成各通道自己的格式响应再转回来。这样上层完全无感。注意容错切换不要跨任务类型切换。代码任务的主通道挂了备用通道也必须是代码能力强的不能随便切到一个通用通道否则输出质量没法保证。2.4 配置驱动所有通道信息集中在一份 models.json 里整个网关的行为由一份配置文件驱动我把它命名为 models.json。里面定义了每个通道的名称、接口地址、鉴权方式、支持的模型列表、擅长的任务类型、优先级、超时时间等。网关启动时读取这份配置运行时根据配置做路由。这样做的好处是增删通道不用改代码改配置重启就行。而且配置可以版本管理出问题了回滚配置即可。我见过有人把通道信息硬编码在代码里结果加一个通道要改好几处容易漏。配置驱动虽然多写一个文件但长期维护成本低得多。3. 核心细节解析与实操要点3.1 models.json 的结构设计这份配置文件是整个方案的核心结构设计得好不好直接决定后续维护难度。我的结构是这样的顶层是一个 channels 数组每个元素代表一个通道。每个通道包含 id、name、base_url、api_key、format、models、strengths、priority、timeout 这些字段。format 字段很关键它告诉网关这个通道用的是什么接口格式目前我支持 openai 和 custom 两种。openai 格式直接透传custom 格式需要走转换逻辑。strengths 是一个数组标记这个通道擅长的任务类型比如 code、long_text、translation、fast_chat。priority 是优先级数字越小越优先。我踩过一个坑一开始没加 timeout 字段结果某个通道响应特别慢把整个请求拖死了。后来给每个通道单独设了超时时间默认 30 秒快的通道设 15 秒慢的设 60 秒。超时之后自动切备用通道整体响应时间就稳定了。3.2 任务类型判断的实现方式任务类型判断我用了最简单的规则匹配没有上复杂的分类模型。具体逻辑是先看请求里有没有代码特征比如 代码块标记、def、function、class 这些关键词有就标记为 code 任务。再看文本长度超过 4000 字符标记为 long_text。再看有没有翻译指令比如翻译成、translate这些词有就标记为 translation。剩下的都归为 fast_chat。这套规则听起来粗糙但实测准确率够用。因为免费模型的使用场景本来就比较固定大部分请求要么是写代码要么是问答要么是翻译边界很清晰。如果你发现误判比较多可以再加规则比如检测特定语言的关键词。提示规则匹配的顺序很重要。先判断 code再判断 long_text最后判断 translation。因为一个长文本里可能包含代码这时候应该优先按 code 处理。3.3 请求格式转换的关键点不同通道的接口格式差异主要体现在几个地方鉴权头的字段名、请求体的参数命名、响应体的结构。比如有的通道用 Authorization: Bearer xxx有的用 x-api-key: xxx。有的通道把消息放在 messages 字段有的放在 input 字段。我的做法是在网关里定义一个内部统一格式所有进来的请求先转成内部格式出去的时候再转成目标通道的格式。内部格式我直接用了 OpenAI 的格式因为大部分免费通道都兼容这个格式转换工作量最小。对于不兼容的通道写一个适配器函数单独处理。这里有个容易忽略的点响应体的错误处理。不同通道返回错误时的结构不一样有的返回 {error: {message: ...}}有的返回 {code: 400, msg: ...}。网关需要把这些错误统一成一种格式再返回给上层否则 WorkBuddy 那边没法正确处理。3.4 鉴权信息的安全存放14 个通道就有 14 组鉴权信息这些信息不能明文写在代码里也不能提交到版本库。我的做法是把 models.json 里的 api_key 字段留空实际值放在一个单独的 secrets.json 文件里这个文件加到 .gitignore 里不提交。网关启动时合并这两个文件。另外网关本身可以加一层简单的访问控制比如只允许本地访问或者加一个固定的 token 校验。虽然是在本地跑但多一层防护没坏处。我试过不加任何防护结果局域网里其他设备也能访问虽然没什么大风险但总归不太稳妥。4. 实操过程与核心环节实现4.1 环境准备与依赖安装这套方案对运行环境要求很低Python 3.8 以上就行。我用的是 FastAPI 加 httpxFastAPI 负责提供 HTTP 服务httpx 负责转发请求。安装命令很简单pip install fastapi uvicorn httpx如果你不想用 Python用 Node.js 的 Express 加 axios 也能实现逻辑是一样的。我选 Python 是因为配置文件的解析和格式转换写起来更顺手。目录结构我这样组织项目根目录下放 gateway.py 主程序、models.json 通道配置、secrets.json 鉴权信息、router_rules.json 路由规则。日志输出到 logs 目录按天切分。这样结构清晰找东西方便。4.2 网关主程序的编写主程序的核心逻辑分四步接收请求、判断任务类型、选择通道、转发并返回。我用 FastAPI 写了一个 POST 接口路径是 /v1/chat/completions这样 WorkBuddy 那边配置的时候直接填本地地址加这个路径就行。判断任务类型的函数我单独抽出来输入是请求体输出是任务类型字符串。选择通道的函数根据任务类型和通道的 strengths 字段做匹配匹配到多个就按 priority 排序取第一个。转发函数负责格式转换、发送请求、处理超时和错误。代码里有个细节要注意转发请求的时候要设置合理的超时时间并且捕获所有异常。我一开始没捕获 httpx 的超时异常结果某个通道超时之后整个网关进程都卡住了。后来加了 try-except 包裹超时之后返回一个标准错误同时触发备用通道重试。4.3 路由规则的配置与调优路由规则我放在 router_rules.json 里结构是任务类型到通道 id 列表的映射。比如 code 任务对应 [channel_a, channel_b, channel_c]按顺序尝试。这样调整路由策略不用改代码改这个文件就行。调优的过程是这样的先跑一段时间记录每个通道在每个任务类型下的成功率和响应时间。然后根据数据调整优先级。成功率低的通道降级响应慢的通道往后排。我大概跑了一周左右路由规则就基本稳定了。这里有个经验不要频繁调整路由规则。每次调整之后需要观察一段时间才能看出效果频繁调整会导致数据混乱没法判断哪个配置更好。我一般一周调一次每次只改一两个通道的优先级。4.4 WorkBuddy 侧的接入配置WorkBuddy 那边只需要改一个地方把模型接入地址改成网关的本地地址比如 http://127.0.0.1:8000/v1。模型名称随便填一个因为网关不关心模型名称只关心请求内容。鉴权信息填网关的 token如果网关没设 token 就随便填一个。改完之后测试一下发一个简单的请求看网关日志里有没有正确路由。我一开始忘了改 WorkBuddy 的超时设置结果网关还在处理WorkBuddy 那边已经超时了。后来把 WorkBuddy 的超时时间调到比网关最长超时时间还长问题就解决了。注意WorkBuddy 的模型配置里如果有测试连接功能测试的时候可能会发一个空请求网关要能处理这种情况返回一个友好的提示而不是直接报错。4.5 日志与监控的搭建日志我分两种访问日志和错误日志。访问日志记录每个请求的任务类型、选择的通道、响应时间、是否成功。错误日志记录失败请求的详细信息包括请求体、错误原因、重试情况。有了这些日志排查问题就方便多了。比如发现某个任务类型经常失败看日志就知道是哪个通道的问题。我还在网关里加了一个简单的统计接口返回每个通道的成功率和平均响应时间方便随时查看。监控方面我没上复杂的工具就写了一个定时脚本每小时统计一次日志如果某个通道成功率低于阈值就发个提醒。提醒方式很简单写到一个文件里我定期看一眼就行。免费通道本来就不稳定有个基本的监控就够了不用搞太重。5. 常见问题与排查技巧实录5.1 通道限流导致请求失败免费通道限流是最常见的问题。表现是请求返回 429 状态码或者返回一个包含rate limit的错误信息。我的处理方式是遇到限流错误立即切换到备用通道同时把这个通道标记为冷却中冷却时间设 60 秒冷却期内不再路由到这个通道。冷却机制很关键。如果不加冷却网关会一直往限流的通道发请求每次都失败浪费时间和额度。加了冷却之后限流通道会自动被跳过等冷却结束再重新尝试。我实测下来这个机制能把整体成功率提升不少。5.2 响应格式不一致导致解析失败不同通道返回的响应结构不一样有的把内容放在 choices[0].message.content有的放在 output.text有的放在 data.result。网关需要把这些统一成一种格式再返回。我一开始没做统一结果 WorkBuddy 那边有时候能解析有时候报错。解决办法是在网关里加一层响应适配根据通道的 format 字段做转换。openai 格式的直接透传custom 格式的走适配器函数。适配器函数里用 try-except 包裹解析失败就返回一个标准错误避免整个请求崩溃。5.3 长文本请求被截断有些免费通道对输入长度有限制超过限制会截断或者报错。我的处理方式是在路由之前先检查文本长度如果超过某个通道的限制就跳过这个通道选择支持更长文本的通道。如果所有通道都超限就返回一个提示建议用户分段处理。这里有个细节不同通道的长度限制不一样有的按字符算有的按 token 算。我在 models.json 里给每个通道加了一个 max_length 字段单位统一用字符token 限制按 1 token 约等于 4 字符粗略换算。虽然不精确但够用。5.4 网关启动失败或端口占用网关启动失败最常见的原因是端口被占用。默认端口 8000 经常被其他服务占用改一个不常用的端口就行比如 8765。启动命令里指定端口uvicorn gateway:app --host 127.0.0.1 --port 8765另一个常见原因是配置文件格式错误。models.json 里少一个逗号或者多一个括号都会导致解析失败。我的做法是启动前先用 Python 的 json 模块校验一遍有问题直接报错避免启动到一半才失败。5.5 常见问题速查表问题现象可能原因排查方法解决方案请求返回 429通道限流查看日志中的状态码切换备用通道加冷却机制响应解析失败格式不兼容对比响应结构与预期加响应适配层请求超时通道响应慢查看各通道响应时间调整超时时间降级慢通道长文本报错超出长度限制检查文本长度与通道限制路由到长文本通道或分段网关启动失败端口占用或配置错误查看启动日志换端口校验配置文件所有通道都失败网络问题或配置全错逐个通道测试检查网络核对鉴权信息5.6 几个我踩过的坑第一个坑是没做请求去重。有时候 WorkBuddy 会重复发送同一个请求网关每次都转发浪费额度。后来我加了一个简单的去重机制用请求内容的哈希值做 key5 秒内相同的请求直接返回缓存结果。第二个坑是日志写得太详细把完整的请求体和响应体都写进去了结果日志文件涨得飞快。后来改成只记录关键信息请求体只记录前 200 个字符响应体只记录状态和长度。需要详细排查的时候再临时开启全量日志。第三个坑是忘了处理流式响应。有些通道支持流式输出WorkBuddy 也期望流式返回。我一开始只处理了非流式结果流式请求全部失败。后来在网关里加了流式转发的逻辑用 httpx 的 stream 方法逐块转发问题才解决。6. 路由策略的进阶调优与扩展思路6.1 基于历史成功率的动态权重固定优先级的路由策略用久了会发现一个问题某个通道虽然优先级高但最近成功率下降了还是会被优先选中。所以我后来加了一个动态权重机制根据最近一段时间的成功率调整通道的排序。成功率高的通道权重高更容易被选中。具体做法是每次请求结束后更新通道的统计信息包括成功次数、失败次数、平均响应时间。路由的时候计算一个综合得分得分高的优先。得分公式大概是成功率乘以 0.7 加上响应速度得分乘以 0.3。这个公式可以根据自己的偏好调整。6.2 按时间段切换通道有些免费通道在不同时间段的稳定性不一样比如白天限流严重晚上比较稳定。我加了一个时间段规则在 models.json 里给通道配置可用的时间段路由的时候检查当前时间是否在可用范围内。不在范围内的通道直接跳过。这个机制对提升稳定性帮助很大。我观察了一段时间发现某些通道在特定时间段确实表现更好配置之后整体成功率又上了一个台阶。6.3 扩展更多通道的方法加新通道的流程很简单在 models.json 的 channels 数组里加一条记录填好 id、base_url、api_key、format、strengths、priority、timeout、max_length 这些字段。然后在 router_rules.json 里把新通道加到对应任务类型的列表里。重启网关新通道就生效了。加通道的时候要注意 format 字段。如果新通道兼容 OpenAI 格式format 填 openai 就行不用写适配器。如果不兼容需要写一个适配器函数在网关的 adapters 目录里加一个文件然后在配置里引用。适配器函数的逻辑就是请求格式转换加响应格式转换照着已有的适配器改就行。6.4 本地缓存减少重复请求免费额度有限能省则省。我在网关里加了一层本地缓存用 SQLite 存请求和响应的映射。相同的请求在缓存有效期內直接返回缓存结果不再转发到通道。缓存有效期设 10 分钟对于重复性高的任务效果很明显。缓存 key 用请求内容的哈希值这样即使请求的其他字段有微小差异只要核心内容一样就能命中缓存。缓存清理用定时任务每天清理一次过期数据。SQLite 文件放在本地不占多少空间。6.5 把网关做成系统服务每次手动启动网关太麻烦我把它做成了系统服务开机自动启动。Linux 下用 systemd写一个 service 文件放到 /etc/systemd/system/ 目录下设置好启动命令和工作目录enable 一下就行。Windows 下可以用 nssm 把 Python 脚本注册成服务。做成服务之后有个好处网关崩溃了会自动重启。免费通道不稳定网关偶尔会因为某个通道的异常响应崩溃自动重启能保证服务一直可用。我还在服务配置里加了日志重定向把标准输出和错误输出都写到日志文件里方便排查。6.6 安全方面的几点考虑虽然是本地网关但安全方面还是要注意几点。第一鉴权信息不要明文存放用单独的 secrets 文件并且不提交版本库。第二网关只监听本地地址不要监听 0.0.0.0避免局域网其他设备访问。第三日志里不要记录完整的鉴权信息只记录通道 id 就行。如果需要在多台设备上使用可以考虑把网关部署在一台常开的机器上其他设备通过内网地址访问。但这时候一定要加访问控制比如固定 token 校验避免被随意调用。我目前是单机使用网关只监听 127.0.0.1安全性够用。6.7 性能优化的几个小技巧网关本身的性能开销很小主要瓶颈在转发请求的网络延迟上。优化方向有几个一是用连接池复用 HTTP 连接避免每次请求都新建连接二是并发处理多个请求用异步 IO 而不是同步阻塞三是缓存热点请求减少实际转发次数。我用 httpx 的 AsyncClient 做转发配合 FastAPI 的异步接口单机跑几百个并发请求没问题。连接池大小设成 20超时时间按通道单独配置。实测下来网关本身增加延迟在 10 毫秒以内基本可以忽略。6.8 后续可以扩展的方向这套方案目前满足我的日常使用但还有几个可以扩展的方向。一是加一个简单的 Web 界面可视化查看各通道的状态和统计信息不用每次都看日志文件。二是支持更多任务类型比如图片生成、语音转文字把路由逻辑扩展到多模态场景。三是加一个自动测试功能定期向各通道发测试请求提前发现不可用的通道。不过这些扩展都要看实际需求如果当前方案够用没必要为了扩展而扩展。我个人的原则是先跑起来遇到问题再优化不要一开始就设计得太复杂。免费通道本身就在变化方案也要跟着调整保持简单灵活最重要。我在实际使用中最大的体会是路由策略没有最优解只有最适合当前通道状态的解。免费通道的可用性随时在变今天好用的通道明天可能就限流了。所以关键是建立一套能快速调整的机制配置驱动加动态权重比写死逻辑要灵活得多。另外日志一定要记好没有日志就没法调优这是整个方案里最容易被忽略但最重要的一环。 本地网关整合14个免费模型通道：自动路由与容错实践
1. 为什么要把十几个免费模型通道塞进一个入口我最早用 WorkBuddy 的时候配置里塞了七八个免费模型的接入点每次切换任务都得手动改一遍配置写代码用一个、写文档换一个、做翻译再换一个一天下来光切模型就浪费不少时间。后来我把 14 个免费通道全部整合到一个本地网关里对外只暴露一个入口内部按任务类型自动路由效率直接翻倍。这套方案的核心思路就是用一层轻量路由把多个免费模型的差异屏蔽掉让调用方只关心任务本身不关心背后是谁在干活。先说清楚这套东西解决的是什么问题。免费模型通道有几个共性痛点一是每个通道的接口格式、鉴权方式、参数命名都不一样有的用 OpenAI 兼容格式有的自己搞一套二是免费额度有限单个通道跑不了几个请求就限流了三是不同模型擅长的任务不一样有的写代码强有的长文本处理好有的响应快但质量一般。如果每次都手动选根本忙不过来。所以需要一个中间层把这些差异全部吃掉对外提供统一的调用方式同时根据任务特征自动挑最合适的通道。适合谁来参考这套方案如果你手上有多个免费模型的接入权限又不想每次手动切换如果你在本地跑 WorkBuddy 或者类似的工作台工具想让它自动调用不同模型如果你对本地网关、路由分发这类东西感兴趣想自己搭一套玩玩那这篇内容就是写给你的。不需要多深的后端功底能看懂 JSON 配置、会跑简单的本地服务就行。我用的方案不依赖任何特定平台核心就是一个本地 HTTP 服务加一份路由配置表。WorkBuddy 那边只需要把模型接入地址指向本地网关剩下的路由逻辑全部在网关内部完成。下面我从整体设计开始拆把每个环节的考量和实操细节都讲透。2. 整体架构设计与路由思路拆解2.1 核心架构三层结构各管各的事整套方案分三层。最上层是 WorkBuddy 工作台它只认一个模型入口就是本地网关的地址。中间层是路由网关负责接收请求、判断任务类型、选择目标通道、转发请求、处理响应。最下层是 14 个免费模型通道每个通道有自己的接口地址和鉴权信息。这样分层的好处很明显。WorkBuddy 那边完全不用改它以为自己只连了一个模型。路由网关是独立进程改路由规则不用动 WorkBuddy 的配置。底层通道增减也不影响上层加一个新通道只需要在网关配置里加一条记录。我试过把路由逻辑直接写在 WorkBuddy 的配置里结果发现根本行不通因为 WorkBuddy 的模型配置不支持条件判断只能指定一个固定的接口地址。所以必须把路由逻辑外置用一个独立的服务来承担。2.2 路由策略按任务特征匹配不按模型名字硬编码路由的核心是判断这个请求该走哪个通道。我的做法不是简单轮询而是根据请求内容里的特征来匹配。具体来说看几个维度请求里有没有代码块或者代码相关的关键词、文本长度是多少、是不是翻译任务、是不是需要长上下文。举个例子如果请求里包含大量代码片段就优先路由到代码能力强的通道如果是长文档摘要就路由到上下文窗口大的通道如果是快速问答就路由到响应速度快的通道。这些判断逻辑全部写在网关的路由规则里用简单的关键词匹配和长度阈值就能实现不需要上机器学习那一套。为什么不用轮询因为轮询会导致代码任务被分配到不擅长代码的模型上输出质量直接下降。免费通道本来就参差不齐必须扬长避短。我实测下来按任务特征路由比轮询的可用率高出不少尤其是代码类任务匹配对了通道之后基本一次就能用。2.3 容错设计一个通道挂了自动切下一个免费通道最大的问题是不稳定随时可能限流或者超时。所以路由网关必须带容错。我的做法是每个任务类型配置一个主通道和两个备用通道主通道请求失败或者超时自动切到备用通道重试。重试次数限制在两次以内避免无限循环。这里有个细节要注意切换通道之后请求格式可能需要转换。比如主通道用 OpenAI 格式备用通道用另一种格式网关内部要做格式适配。我在网关里加了一层格式转换模块把统一格式的请求转成各通道自己的格式响应再转回来。这样上层完全无感。注意容错切换不要跨任务类型切换。代码任务的主通道挂了备用通道也必须是代码能力强的不能随便切到一个通用通道否则输出质量没法保证。2.4 配置驱动所有通道信息集中在一份 models.json 里整个网关的行为由一份配置文件驱动我把它命名为 models.json。里面定义了每个通道的名称、接口地址、鉴权方式、支持的模型列表、擅长的任务类型、优先级、超时时间等。网关启动时读取这份配置运行时根据配置做路由。这样做的好处是增删通道不用改代码改配置重启就行。而且配置可以版本管理出问题了回滚配置即可。我见过有人把通道信息硬编码在代码里结果加一个通道要改好几处容易漏。配置驱动虽然多写一个文件但长期维护成本低得多。3. 核心细节解析与实操要点3.1 models.json 的结构设计这份配置文件是整个方案的核心结构设计得好不好直接决定后续维护难度。我的结构是这样的顶层是一个 channels 数组每个元素代表一个通道。每个通道包含 id、name、base_url、api_key、format、models、strengths、priority、timeout 这些字段。format 字段很关键它告诉网关这个通道用的是什么接口格式目前我支持 openai 和 custom 两种。openai 格式直接透传custom 格式需要走转换逻辑。strengths 是一个数组标记这个通道擅长的任务类型比如 code、long_text、translation、fast_chat。priority 是优先级数字越小越优先。我踩过一个坑一开始没加 timeout 字段结果某个通道响应特别慢把整个请求拖死了。后来给每个通道单独设了超时时间默认 30 秒快的通道设 15 秒慢的设 60 秒。超时之后自动切备用通道整体响应时间就稳定了。3.2 任务类型判断的实现方式任务类型判断我用了最简单的规则匹配没有上复杂的分类模型。具体逻辑是先看请求里有没有代码特征比如 代码块标记、def、function、class 这些关键词有就标记为 code 任务。再看文本长度超过 4000 字符标记为 long_text。再看有没有翻译指令比如翻译成、translate这些词有就标记为 translation。剩下的都归为 fast_chat。这套规则听起来粗糙但实测准确率够用。因为免费模型的使用场景本来就比较固定大部分请求要么是写代码要么是问答要么是翻译边界很清晰。如果你发现误判比较多可以再加规则比如检测特定语言的关键词。提示规则匹配的顺序很重要。先判断 code再判断 long_text最后判断 translation。因为一个长文本里可能包含代码这时候应该优先按 code 处理。3.3 请求格式转换的关键点不同通道的接口格式差异主要体现在几个地方鉴权头的字段名、请求体的参数命名、响应体的结构。比如有的通道用 Authorization: Bearer xxx有的用 x-api-key: xxx。有的通道把消息放在 messages 字段有的放在 input 字段。我的做法是在网关里定义一个内部统一格式所有进来的请求先转成内部格式出去的时候再转成目标通道的格式。内部格式我直接用了 OpenAI 的格式因为大部分免费通道都兼容这个格式转换工作量最小。对于不兼容的通道写一个适配器函数单独处理。这里有个容易忽略的点响应体的错误处理。不同通道返回错误时的结构不一样有的返回 {error: {message: ...}}有的返回 {code: 400, msg: ...}。网关需要把这些错误统一成一种格式再返回给上层否则 WorkBuddy 那边没法正确处理。3.4 鉴权信息的安全存放14 个通道就有 14 组鉴权信息这些信息不能明文写在代码里也不能提交到版本库。我的做法是把 models.json 里的 api_key 字段留空实际值放在一个单独的 secrets.json 文件里这个文件加到 .gitignore 里不提交。网关启动时合并这两个文件。另外网关本身可以加一层简单的访问控制比如只允许本地访问或者加一个固定的 token 校验。虽然是在本地跑但多一层防护没坏处。我试过不加任何防护结果局域网里其他设备也能访问虽然没什么大风险但总归不太稳妥。4. 实操过程与核心环节实现4.1 环境准备与依赖安装这套方案对运行环境要求很低Python 3.8 以上就行。我用的是 FastAPI 加 httpxFastAPI 负责提供 HTTP 服务httpx 负责转发请求。安装命令很简单pip install fastapi uvicorn httpx如果你不想用 Python用 Node.js 的 Express 加 axios 也能实现逻辑是一样的。我选 Python 是因为配置文件的解析和格式转换写起来更顺手。目录结构我这样组织项目根目录下放 gateway.py 主程序、models.json 通道配置、secrets.json 鉴权信息、router_rules.json 路由规则。日志输出到 logs 目录按天切分。这样结构清晰找东西方便。4.2 网关主程序的编写主程序的核心逻辑分四步接收请求、判断任务类型、选择通道、转发并返回。我用 FastAPI 写了一个 POST 接口路径是 /v1/chat/completions这样 WorkBuddy 那边配置的时候直接填本地地址加这个路径就行。判断任务类型的函数我单独抽出来输入是请求体输出是任务类型字符串。选择通道的函数根据任务类型和通道的 strengths 字段做匹配匹配到多个就按 priority 排序取第一个。转发函数负责格式转换、发送请求、处理超时和错误。代码里有个细节要注意转发请求的时候要设置合理的超时时间并且捕获所有异常。我一开始没捕获 httpx 的超时异常结果某个通道超时之后整个网关进程都卡住了。后来加了 try-except 包裹超时之后返回一个标准错误同时触发备用通道重试。4.3 路由规则的配置与调优路由规则我放在 router_rules.json 里结构是任务类型到通道 id 列表的映射。比如 code 任务对应 [channel_a, channel_b, channel_c]按顺序尝试。这样调整路由策略不用改代码改这个文件就行。调优的过程是这样的先跑一段时间记录每个通道在每个任务类型下的成功率和响应时间。然后根据数据调整优先级。成功率低的通道降级响应慢的通道往后排。我大概跑了一周左右路由规则就基本稳定了。这里有个经验不要频繁调整路由规则。每次调整之后需要观察一段时间才能看出效果频繁调整会导致数据混乱没法判断哪个配置更好。我一般一周调一次每次只改一两个通道的优先级。4.4 WorkBuddy 侧的接入配置WorkBuddy 那边只需要改一个地方把模型接入地址改成网关的本地地址比如 http://127.0.0.1:8000/v1。模型名称随便填一个因为网关不关心模型名称只关心请求内容。鉴权信息填网关的 token如果网关没设 token 就随便填一个。改完之后测试一下发一个简单的请求看网关日志里有没有正确路由。我一开始忘了改 WorkBuddy 的超时设置结果网关还在处理WorkBuddy 那边已经超时了。后来把 WorkBuddy 的超时时间调到比网关最长超时时间还长问题就解决了。注意WorkBuddy 的模型配置里如果有测试连接功能测试的时候可能会发一个空请求网关要能处理这种情况返回一个友好的提示而不是直接报错。4.5 日志与监控的搭建日志我分两种访问日志和错误日志。访问日志记录每个请求的任务类型、选择的通道、响应时间、是否成功。错误日志记录失败请求的详细信息包括请求体、错误原因、重试情况。有了这些日志排查问题就方便多了。比如发现某个任务类型经常失败看日志就知道是哪个通道的问题。我还在网关里加了一个简单的统计接口返回每个通道的成功率和平均响应时间方便随时查看。监控方面我没上复杂的工具就写了一个定时脚本每小时统计一次日志如果某个通道成功率低于阈值就发个提醒。提醒方式很简单写到一个文件里我定期看一眼就行。免费通道本来就不稳定有个基本的监控就够了不用搞太重。5. 常见问题与排查技巧实录5.1 通道限流导致请求失败免费通道限流是最常见的问题。表现是请求返回 429 状态码或者返回一个包含rate limit的错误信息。我的处理方式是遇到限流错误立即切换到备用通道同时把这个通道标记为冷却中冷却时间设 60 秒冷却期内不再路由到这个通道。冷却机制很关键。如果不加冷却网关会一直往限流的通道发请求每次都失败浪费时间和额度。加了冷却之后限流通道会自动被跳过等冷却结束再重新尝试。我实测下来这个机制能把整体成功率提升不少。5.2 响应格式不一致导致解析失败不同通道返回的响应结构不一样有的把内容放在 choices[0].message.content有的放在 output.text有的放在 data.result。网关需要把这些统一成一种格式再返回。我一开始没做统一结果 WorkBuddy 那边有时候能解析有时候报错。解决办法是在网关里加一层响应适配根据通道的 format 字段做转换。openai 格式的直接透传custom 格式的走适配器函数。适配器函数里用 try-except 包裹解析失败就返回一个标准错误避免整个请求崩溃。5.3 长文本请求被截断有些免费通道对输入长度有限制超过限制会截断或者报错。我的处理方式是在路由之前先检查文本长度如果超过某个通道的限制就跳过这个通道选择支持更长文本的通道。如果所有通道都超限就返回一个提示建议用户分段处理。这里有个细节不同通道的长度限制不一样有的按字符算有的按 token 算。我在 models.json 里给每个通道加了一个 max_length 字段单位统一用字符token 限制按 1 token 约等于 4 字符粗略换算。虽然不精确但够用。5.4 网关启动失败或端口占用网关启动失败最常见的原因是端口被占用。默认端口 8000 经常被其他服务占用改一个不常用的端口就行比如 8765。启动命令里指定端口uvicorn gateway:app --host 127.0.0.1 --port 8765另一个常见原因是配置文件格式错误。models.json 里少一个逗号或者多一个括号都会导致解析失败。我的做法是启动前先用 Python 的 json 模块校验一遍有问题直接报错避免启动到一半才失败。5.5 常见问题速查表问题现象可能原因排查方法解决方案请求返回 429通道限流查看日志中的状态码切换备用通道加冷却机制响应解析失败格式不兼容对比响应结构与预期加响应适配层请求超时通道响应慢查看各通道响应时间调整超时时间降级慢通道长文本报错超出长度限制检查文本长度与通道限制路由到长文本通道或分段网关启动失败端口占用或配置错误查看启动日志换端口校验配置文件所有通道都失败网络问题或配置全错逐个通道测试检查网络核对鉴权信息5.6 几个我踩过的坑第一个坑是没做请求去重。有时候 WorkBuddy 会重复发送同一个请求网关每次都转发浪费额度。后来我加了一个简单的去重机制用请求内容的哈希值做 key5 秒内相同的请求直接返回缓存结果。第二个坑是日志写得太详细把完整的请求体和响应体都写进去了结果日志文件涨得飞快。后来改成只记录关键信息请求体只记录前 200 个字符响应体只记录状态和长度。需要详细排查的时候再临时开启全量日志。第三个坑是忘了处理流式响应。有些通道支持流式输出WorkBuddy 也期望流式返回。我一开始只处理了非流式结果流式请求全部失败。后来在网关里加了流式转发的逻辑用 httpx 的 stream 方法逐块转发问题才解决。6. 路由策略的进阶调优与扩展思路6.1 基于历史成功率的动态权重固定优先级的路由策略用久了会发现一个问题某个通道虽然优先级高但最近成功率下降了还是会被优先选中。所以我后来加了一个动态权重机制根据最近一段时间的成功率调整通道的排序。成功率高的通道权重高更容易被选中。具体做法是每次请求结束后更新通道的统计信息包括成功次数、失败次数、平均响应时间。路由的时候计算一个综合得分得分高的优先。得分公式大概是成功率乘以 0.7 加上响应速度得分乘以 0.3。这个公式可以根据自己的偏好调整。6.2 按时间段切换通道有些免费通道在不同时间段的稳定性不一样比如白天限流严重晚上比较稳定。我加了一个时间段规则在 models.json 里给通道配置可用的时间段路由的时候检查当前时间是否在可用范围内。不在范围内的通道直接跳过。这个机制对提升稳定性帮助很大。我观察了一段时间发现某些通道在特定时间段确实表现更好配置之后整体成功率又上了一个台阶。6.3 扩展更多通道的方法加新通道的流程很简单在 models.json 的 channels 数组里加一条记录填好 id、base_url、api_key、format、strengths、priority、timeout、max_length 这些字段。然后在 router_rules.json 里把新通道加到对应任务类型的列表里。重启网关新通道就生效了。加通道的时候要注意 format 字段。如果新通道兼容 OpenAI 格式format 填 openai 就行不用写适配器。如果不兼容需要写一个适配器函数在网关的 adapters 目录里加一个文件然后在配置里引用。适配器函数的逻辑就是请求格式转换加响应格式转换照着已有的适配器改就行。6.4 本地缓存减少重复请求免费额度有限能省则省。我在网关里加了一层本地缓存用 SQLite 存请求和响应的映射。相同的请求在缓存有效期內直接返回缓存结果不再转发到通道。缓存有效期设 10 分钟对于重复性高的任务效果很明显。缓存 key 用请求内容的哈希值这样即使请求的其他字段有微小差异只要核心内容一样就能命中缓存。缓存清理用定时任务每天清理一次过期数据。SQLite 文件放在本地不占多少空间。6.5 把网关做成系统服务每次手动启动网关太麻烦我把它做成了系统服务开机自动启动。Linux 下用 systemd写一个 service 文件放到 /etc/systemd/system/ 目录下设置好启动命令和工作目录enable 一下就行。Windows 下可以用 nssm 把 Python 脚本注册成服务。做成服务之后有个好处网关崩溃了会自动重启。免费通道不稳定网关偶尔会因为某个通道的异常响应崩溃自动重启能保证服务一直可用。我还在服务配置里加了日志重定向把标准输出和错误输出都写到日志文件里方便排查。6.6 安全方面的几点考虑虽然是本地网关但安全方面还是要注意几点。第一鉴权信息不要明文存放用单独的 secrets 文件并且不提交版本库。第二网关只监听本地地址不要监听 0.0.0.0避免局域网其他设备访问。第三日志里不要记录完整的鉴权信息只记录通道 id 就行。如果需要在多台设备上使用可以考虑把网关部署在一台常开的机器上其他设备通过内网地址访问。但这时候一定要加访问控制比如固定 token 校验避免被随意调用。我目前是单机使用网关只监听 127.0.0.1安全性够用。6.7 性能优化的几个小技巧网关本身的性能开销很小主要瓶颈在转发请求的网络延迟上。优化方向有几个一是用连接池复用 HTTP 连接避免每次请求都新建连接二是并发处理多个请求用异步 IO 而不是同步阻塞三是缓存热点请求减少实际转发次数。我用 httpx 的 AsyncClient 做转发配合 FastAPI 的异步接口单机跑几百个并发请求没问题。连接池大小设成 20超时时间按通道单独配置。实测下来网关本身增加延迟在 10 毫秒以内基本可以忽略。6.8 后续可以扩展的方向这套方案目前满足我的日常使用但还有几个可以扩展的方向。一是加一个简单的 Web 界面可视化查看各通道的状态和统计信息不用每次都看日志文件。二是支持更多任务类型比如图片生成、语音转文字把路由逻辑扩展到多模态场景。三是加一个自动测试功能定期向各通道发测试请求提前发现不可用的通道。不过这些扩展都要看实际需求如果当前方案够用没必要为了扩展而扩展。我个人的原则是先跑起来遇到问题再优化不要一开始就设计得太复杂。免费通道本身就在变化方案也要跟着调整保持简单灵活最重要。我在实际使用中最大的体会是路由策略没有最优解只有最适合当前通道状态的解。免费通道的可用性随时在变今天好用的通道明天可能就限流了。所以关键是建立一套能快速调整的机制配置驱动加动态权重比写死逻辑要灵活得多。另外日志一定要记好没有日志就没法调优这是整个方案里最容易被忽略但最重要的一环。