## 摘要
Harness²框架提出了一套双层递归机制，能够在基础模型权重完全冻结的前提下，持续对代理运行时Harness组件进行迭代优化。任务层递归通过「提议-探测-组装」循环，针对当前任务迭代优化正在生效的Harness配置；演化递归则将经过验证的Harness修改方案、执行轨迹沉淀为经验库，支撑优化能力跨任务迁移。该框架可编辑对象划分为八大模块化组件。智能代理的能力上限并不仅仅由底层大模型决定，配套的Harness体系同样起到关键作用，其中包含系统提示词、记忆库、技能定义、工具绑定、任务脚手架等组件。这一关系可以被概括为公式：`Agent = Model + Harness`。西北大学与Google DeepMind的研究人员在论文《Harness²: Recursive Agent Harnessing for an Open World》中首次提出该设计。
开放式代理工作流会给静态Harness方案带来两大硬性约束。第一，全新任务往往缺少标准答案或者可靠验证器，很难确认一处Harness修改是否真正带来功能收益。第二，针对单一任务精细调优后的Harness容易对领域特征过拟合，在后续未见过的新任务上泛化效果较差。Harness²将优化流水线拆分为两套独立的递归循环，以此解决上述问题：任务递归负责修改Harness适配当前任务；演化递归把本轮调优中可复用的有效经验打包，供后续任务使用。本文将拆解它的组件设计、递归执行流程、基准测试数据、失效模式以及落地取舍。
## 1. Harness八大可编辑组件组
论文作者将可调整的Harness对象拆分为8个独立组件类别，每一类都对应独立的运行时实体，每一次Harness版本变更都可以被记录为文件级差异对比。
- 系统提示词、约束规则、长期记忆、工具指令：每一次调用模型时都会重新加载；
- 技能定义：按需懒加载；
- 脚本：依托Bash外壳执行任意自定义操作；
- 子代理：在隔离的执行上下文内承接拆分出来的子任务；
- 插件：嵌入工具调用循环，在API请求、工具迭代链路中注入自定义逻辑。
Harness的修改并不局限于提示文本。流程逻辑可以封装到技能内，确定性的操作步骤可以固化为脚本，独立的子任务负载可以交给子代理处理，运行时安全护栏可以通过插件强制生效。双层递归流程会在全部这八类可编辑组件上迭代运行，不断提出修改方案、开展测试、合并有效的组件变更。
## 2. Harness²的两层递归架构
整个架构分为**任务层递归**与**Harness演化递归（进化递归）**两大层级。
### 2.1 任务层递归：提议-探测-组装
任务递归的基础循环分为三步：生成修改提案、探测候选Harness版本、组装形成更新后的Harness。
1. **提议（Propose）**：Harness编辑器从两个方向产出候选修改方案。通用方案用来优化通用规则、工具调用协议、任务委派逻辑；领域方案注入特定场景的流程约束与行业知识。
2. **探测（Probe）**：每一个候选Harness，都在同一个基础模型、同一个沙箱环境下运行完全一致的目标任务。系统会完整记录执行轨迹与输出产物，对比基线版本和候选版本的运行行为，完成行为对照。行为对照能够为修改方案提供佐证，但无法绝对判定任务结果正确。不同的有效实现路径，本身就会产生不一样的执行轨迹，同时模型采样随机性也会带来干扰。
3. **组装（Compose）**：Harness组装器评估全部候选轨迹、文件变更记录、运行指标，合并筛选出有效的改动、处理冲突规则，或是保留原有Harness不做变更。合并后的版本，将作为下一轮任务迭代使用的激活Harness。
JobBench基准测试中的实例可以直观展示这套流程。基线Harness得分仅为43.1分。通过轨迹排查发现两处核心短板：代理不会跨多个源文件交叉核对数值，并且生成输出之后缺少写入后的校验环节。编辑器新增通用输入清洗脚本、结果校验脚本，同时配套领域专属的对账技能、定向数值校验工具指引。经过组装合并后，新版Harness最终得分提升至77.8分，涨幅达到34.7分。
### 2.2 并行递归与串行递归，拓宽搜索空间
完成一轮「提议-探测-组装」之后，Harness²支持两种递归变体来扩大探索范围：并行递归、串行递归。
- **并行递归**：多个独立Harness候选同时运行，每一个候选探索不同的领域不变量。组装器汇总所有分支结果，合并形成一份最终Harness。该模式可以在固定时间预算内拓宽搜索广度。
- **串行递归**：候选按顺序轮次执行，每一轮都会继承上一轮的Harness状态与验证记录，系统可以保留、微调或是回滚之前的修改。
两种模式都会完整保存执行轨迹与Harness快照，而不只是最终输出结果。当`k>1`时，选择器从已经跑完的候选版本里挑选经过验证的变体送入组装流程；没有体现出可区分收益的候选会直接丢弃，不会写入经验库。研究团队在WB-Code、WB-Office基准上对k取1~5开展对照测试。在测试区间内，性能整体随着k增大而上升，但在Harness Scaling、ReasoningBank测试集上收益不稳定。递归预算增加，并不一定会带来线性的性能提升。
## 3. 演化递归：将验证过的修改写入经验库
当一个任务执行结束后，反思模块（Reflector）复盘全部调优历史：所有候选Harness、探测轨迹、组装决策、最终结果。它会给每一处修改打上证据标签：有益、有害、结论存疑、无法归因。当一个候选版本一次性捆绑多处组件修改，无法定位到底是哪一处改动影响结果时，就会标记为无法归因。框架不会把没有因果证据支撑的结论写入长期记忆。
经过验证的改动会作为持久记录存入经验库。每一条记录包含适用上下文、可迁移的修改范式、配套执行轨迹、置信分数。如果候选版本没有形成可靠的行为对照证据，则标记为`NO_ENTRY`直接丢弃。经验库同时保存完整的Harness快照，以及一份中心索引文件`EXPERIENCE.md`，后续任务既可以读取整套记录，也可以单独复用、适配里面的技能、脚本、规则文件。
关键点：每一个全新任务，都会从空白初始Harness状态`H0`启动，不会直接继承上一个任务结束时的Harness。编辑器会在提议、探测、组装阶段加载经验库，复用历史沉淀的经验。全程基础模型参数保持冻结，只有Harness脚手架会在跨任务过程中持续演化。
## 4. 跨任务迁移定量基准结果
研究人员首先在`k=1`条件下测试单任务优化效果。在三套基准、四种模型+Harness初始配置下，Harness²的表现稳定优于静态基线Harness。提升幅度最高的几组：WorkBuddy-Bench提升11.5分，JobBench提升4.5分，LAB通过率指标提升11.8个百分点。
消融实验单独拆分了经验库、编辑范围、组装步骤各自的贡献。在Gemini 3.5 Flash + OpenCode、`k=1`的配置下：
- 完整Harness²：WorkBuddy-Bench 77.5分，JobBench 36.0分
- 移除经验库：得分下降至74.4、34.2
- 同时移除通用、领域两类编辑范围：得分下降至74.6、32.3
- 移除组装步骤：得分下降至75.9、34.1
另一组消融实验测试「不经过探测执行、直接编辑Harness」的场景：编辑器只复用库内记录，不再运行新探测轨迹时，性能大幅下滑。WB-Code由73.4跌至63.2，WB-Web由69.9跌至65.0。开启`k=1`库复用之后，性能部分回升、贴近基线Harness水平；当积累足够经验、`k=5`时，WB-Code、WB-Web、WB-Office相比静态基线分别提升0.9、4.4、5.1分。这验证了第二层演化递归的价值：在一个任务上投入额外Harness探索，产生的轨迹、组装决策，能够泛化到后续无关任务，优化Harness修改方案。
跨基准迁移实验进一步验证迁移能力。把JobBench的经验记录导入已有的WorkBuddy-Bench Harness后，WB-Code、WB-Web、WB-Office分别提升0.6、0.5、2.9分。迁移效果在不同基础模型、不同测试域之间差异很大。研究团队在OpenCode上使用`k=2`测试，让同一个模型既负责任务执行，也负责Harness编辑。参与测试的GLM-5到Claude Opus 5共五款模型，全部超过自身静态Harness基线，证明这套递归调优流水线，不需要单独部署一个更强的专用编辑模型。
组件复用统计呈现出一个有意思的规律：仅有2%~10%的修改文件，保留了来源库记录一半以上的原始代码。Harness适配是增量微调，而非直接复制粘贴。综合全部基准测试，技能、脚本两类产物合计占到所有组件修改量的一半左右。
持续开展多模型基准测评的团队，往往需要统一接入大量异构模型端点、集中管控调用日志。Treerouter这类托管式API网关可以简化多模型评估工作流，为大批量Harness变体统一提供路由、配额统计能力。在受控沙箱中大规模并行运行探测循环时，这类运维能力会显著降低落地成本。
## 5. 行为对照的局限与失效模式
Harness²依靠行为对照判断修改优劣，这套信号本身存在可量化的误差。论文归纳了九类典型失效场景，这里选取四类高频问题说明：
1. **误选更差候选**：组装器挑选了在局部轨迹上表现更好的Harness，但它会损害任务整体效果。一组WorkBuddy-Code测试案例中，选择器选中得分55的版本，而另一个候选版本得分可达95，选中的改动直接带来41分的性能回撤。
2. **修改池饱和**：旧Harness里固化的规则约束，阻挡新的有效修改。即便存在更优解，搜索空间也会提前收缩。
3. **轨迹相关带来归因错误**：模型采样噪声、固有偏差制造假阳性证据。系统把分数上涨归因于Harness改动，实际上收益来自模型随机采样。
4. **未复核的结果波动**：单次偶然跑通的成功案例，就被认定是稳定提升，缺少重复验证。
作者明确指出：行为对照不能替代标准答案校验。在缺少标准真值的场景下，轨迹对比容易受采样方差、模型固有偏差干扰。在A任务上验证有效的Harness，不一定能稳定迁移到其他领域。哪怕是局部稳定带来正向收益的改动，也可能在后续未见过的子任务上引发连锁降级。
## 6. 算力开销与落地成本
每一轮递归调优都会增加算力消耗。每一个候选Harness都要完整执行模型推理、工具调用、轨迹记录。并行递归可以缩短总耗时，但不会减少token总消耗量。论文只在测试预算范围内刻画了性能与算力的权衡，并没有给出一套适用于全部代理任务的通用成本阈值。
经验库本身也存在维护成本。随着记录持续堆积，团队需要配套机制完成去重、过期记录淘汰、语义检索索引、置信度衰减管理。最优的库管理策略，会随着任务难度、领域相似度、新增轨迹体量动态变化。
## 7. 总结
Harness²给出了一套在冻结基础权重前提下，实现代理能力提升的可行方案。任务层递归依靠「提议-探测-组装」循环，迭代打磨适配当前任务的Harness；演化递归把调优过程里带证据的轨迹沉淀为可复用经验库，实现经过验证的脚手架修改跨任务迁移。基准测试数据在WB-Code、WB-Web、WB-Office、JobBench、WorkBuddy-Bench上都测出正向收益，当经验库复用搭配全新探测执行时，提升效果最为明显。
核心结论：代理能力提升，未必都需要微调模型权重。很多代理失败的根源，来自脚手架本身的缺陷：校验规则不全、领域技能缺失、工具调用指引粗糙、插件安全护栏缺失。该框架最大的短板在于，行为对照是一种不完美的监督信号，容易产生假阳性、归因错误、选出反向退化的Harness版本。生产环境落地时，自动化递归之外，人工复核、不定期真值校验依然是必不可少的安全兜底。
这套双层递归设计，为自优化代理系统提供了实现思路：代理学习的不再只有任务本身，还可以持续学习如何优化自身的运行环境。
# 用 Android 3D 游戏开发给编码大模型做基准：Step 5 Preview、DeepSeek V4 Pro、GLM-5.3 横向实测
了解更多：[https://treerouter.com](https://treerouter.com)
## 摘要
简单的算法练习题、待办事项类应用，无法真正暴露大模型在真实工程场景中的能力上限。复杂的三维交互项目是严苛的端到端测试，因为它同时涉及游戏循环逻辑、三维数学、触摸事件处理、状态管理、移动端适配。本文描述一次受控实操基准测试：让 Step 5 Preview、DeepSeek V4 Pro、GLM-5.3 分别构建一个基于 Three.js、打包进 Android WebView 的三维跑酷游戏。评测指标包括首轮可运行成功率、达到可完整游玩状态所需的对话轮数、人工修复代码量、代码规范度、移动端意识。报告同时记录把 GLM-5.3 通过 vLLM Docker 镜像本地部署时遇到的实际坑点，并给出各模型差异化的适用画像。需要横向评估多款编码模型的团队，可复现这套测试流程来对比实际产出质量，而不是只依赖公开榜单数字。
## 一、为什么 Android 三维跑酷游戏是严格基准
短算法任务频繁出现在模型训练语料里，模型可以通过模式匹配生成看似合理的输出，却体现不出真正的工程判断力。构建一个可运行的移动端 Three.js 跑酷游戏，需要把多个正交的工程要求组合在一起：
1. 游戏循环时序：正确实现 requestAnimationFrame，并配合 delta-time 计算，把物体移动速度与帧率波动解耦。
2. 三维数学逻辑：场景组装、相机追踪、向量变换、碰撞检测的空间判断。
3. 触摸输入处理：通过 touchstart、touchmove、touchend 事件区分滑动与单击，适配移动端交互。
4. 状态与资源管理：组织几何体、材质、音频资源；实现开始、运行、游戏结束、重启的干净状态切换。
5. 移动端适配：视口配置、高 DPI 屏幕适配、帧率稳定性、正确的内存清理。
仅仅渲染一个旋转的三维场景只是及格线。模型之间的真实差距，体现在处理隐式需求上：容错的触摸逻辑、性能节流、游戏重启时的资源清理——这些都不会写进用户提示词。
### 1.1 统一提示词与评测指标
三个模型收到完全相同的提示词：
> 使用 Three.js 和 Android WebView 打包，为 Android 构建一个三维跑酷小游戏。角色沿 Z 轴自动前进，玩家通过左右滑动控制 X 轴水平移动，生成随机高度、随机间距的立方体障碍物。碰撞触发游戏结束，显示总分并提供重启按钮。包含开始界面、音效、计分逻辑与渐进提速。交付一个自包含、可直接在浏览器运行的 HTML，并提供 Android 打包的分步说明。
输出 token 上限统一设为 4096，防止响应被过早截断。定义五个客观评测维度：
1. 首轮可运行率：生成的 HTML 能否在浏览器与真实 Android 硬件上无运行时错误地执行。
2. 达到可完整游玩状态所需的对话轮数（含开始界面、游戏进行、计分、结束、重启）。
3. 人工修复量：人工评测员手动修改的代码行数。
4. 代码规范质量：模块拆分、命名纪律、注释、常量定义规范。
5. 移动端意识：对触摸冲突、帧率下降、视口兼容的主动处理。
### 1.2 为什么选 Three.js + Android WebView
Unity 工程生成不适合作为 LLM 测试。模型能输出 C# 脚本，却无法创建二进制场景资源、prefab 与编辑器配置，大部分工程搭建工作仍要人工完成。纯 Kotlin + OpenGL-ES 对矩阵变换与着色器代码有很高的调试门槛，会显著拉低所有候选模型的首次通过率。
封装进 Android WebView 的 Three.js 在基准测试上优势明显。完整游戏可以放进单个 HTML 文件，一个极简的 Android 原生包装只需少量 Kotlin 行就能把网页内容嵌入 APK。反馈周期短，实验可复现性高。测试既覆盖代码生成能力，也检验模型对真实移动软件发布流程的理解。
## 二、测试环境与 GLM-5.3 vLLM 部署坑点
三个模型运行条件不同，解读最终结果时必须考虑这一因素：
| 模型 | 接入方式 | 运行环境 |
|---|---|---|
| Step 5 Preview | 云端托管的 Agent 编码沙箱 | 托管远程环境，支持会话内迭代改码 |
| DeepSeek V4 Pro | 标准 REST API | 本地脚本客户端处理多轮对话，把上一轮代码与修改需求喂回 |
| GLM-5.3 | 本地自托管推理 | Docker 容器化的 vLLM + 4bit 量化权重，统一推理超参 |
Step 5 Preview 是完整的 Agent 产品，而非裸模型权重 API；它表现出的部分优势来自周边 Agent 循环基础设施，不只是底层模型能力。GLM-5.3 采用本地部署，是为了消除远端 API 方差，并排查社区广泛反馈的 GLM-5.3 与旧版 vLLM 容器镜像兼容性问题。
### 2.1 GLM-5.3 的 vLLM 兼容性关键坑
使用稳定的旧版 vLLM Docker 镜像会直接加载失败：
```
AssertionError: Unsupported architecture 'GLMForCausalLM'
KeyError: 'glm_arch'
```
根因很直接：旧版 vLLM 缺少识别 GLM-5.3 新模型架构的注册表条目。排查人员应检查模型权重的 config.json 中 architectures 字段，并对照 vLLM 变更日志。
容器镜像选择的推荐流程：
1. 对一般稳定的新模型支持，拉取 vllm/vllm-openai:latest。
2. 对尚未进入正式版本的先锋模型，使用 vllm/vllm-openai:nightly。
使用 AWQ 量化模型时还有额外注意点：vLLM kernel 与 autoawq 库版本不匹配时，权重可以加载，但会触发张量并行相关的推理失败，容易被误判为显存耗尽。生产部署必须钉住精确的镜像标识字符串，不要依赖浮动 latest 标签。
### 2.2 统一推理与 Android 运行时设置
GLM-5.3 与 DeepSeek V4 Pro 共用相同的超参数：temperature=0.3、top_p=0.95、max_tokens=4096。Step 5 Preview 运行在托管 Agent 沙箱内，底层采样参数不可调，只能通过提示词措辞施加约束。
全部 HTML 输出都在同一个 Android WebView 配置下加载：
```kotlin
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
webView.settings.mediaPlaybackRequiresUserGesture = false
webView.setLayerType(View.LAYER_TYPE_HARDWARE, null)
```
这样能保证性能或行为差异源于生成的源码，而不是嵌入环境不同。
## 三、各模型实测结果
### 3.1 Step 5 Preview：端到端工程循环能力强
Step 5 Preview 首次生成就交付了自包含 HTML。输出包含开始界面、背景音乐、碰撞音效、实时分数显示与渐进提速，速度参数以可配置常量暴露，而非硬编码魔法数字。初始构建在桌面浏览器与真实 Android 硬件上都能成功运行。
真机验证后暴露出两个移动端缺陷：滑动处理过于灵敏，以及低端硬件开启阴影映射时帧率下降。把观察结果作为反馈回传后，第二次迭代引入了可配置触摸灵敏度常量，以及根据屏幕像素密度条件性开启阴影的逻辑。
生成源码里有几个值得注意的工程选择：游戏循环严格用 requestAnimationFrame 做 delta-time 归一化，避免帧率变化导致速度失真；碰撞检测采用简化的 AABB 包围盒近似，更贴合游戏手感而不是昂贵的高保真网格检测；移动端适配包含 viewport-fit=cover（刘海屏兼容）、touch-action: none（抑制手势）、overscroll-behavior（消除多余页面滚动）。重启逻辑正确重置分数、障碍物集合与音频状态。
主要短板是代码偏长（约 600 行），有时会添加超出最小提示需求的装饰性功能。总体而言，Step 5 Preview 展示了端到端工程循环优势：无需大量人工拼接孤立片段，就能交付可完整游玩的成品。
### 3.2 DeepSeek V4 Pro：需求明确时执行可靠
DeepSeek V4 Pro 首轮也生成了可在浏览器运行的 HTML，但省略了开始界面、音频反馈与障碍物间距变化。它忠实实现了提示词里明确写出的条目，却很少主动推断隐式的产品体验改进。
经过两轮定向人工反馈，开发者补上了开始界面、游戏结束总结屏与音效。进一步修订加入了 1 秒无敌时间戳校验，消除重复碰撞帧触发造成的重复计分。
代码组织是它最大的优势。createScene、createPlayer、spawnObstacle、checkCollision 等函数边界清晰，可调常量集中放在文件顶部。这种结构简化了后续人工修改与调试。
DeepSeek V4 Pro 呈现的是可靠执行者画像：精准完成明确描述的需求，却很少主动补充设计决策。对工程师已持有详细验收清单的场景，这个行为模式很合适。
### 3.3 GLM-5.3（本地部署）：本地控制价值高，人工修复负担也高
换用更新的 vLLM nightly 镜像后，GLM-5.3 成功完成本地推理。但首轮输出包含运行时缺陷：未定义的阴影贴图变量触发 ReferenceError，且游戏重启时未清理障碍物集合，产生幽灵障碍物伪影。人工修复约需改动 30 行源码。
达到完整可玩状态需要三轮对话：修复运行时异常、用 Web-Audio-API 实现离线音效生成（避免外部资源依赖）、构建分段渐进提速逻辑。多轮编辑对既有长文件的上下文保留得很好，但功能诉求必须写得极其具体；模糊措辞如"加音效"，容易生成依赖文件路径的音频标签，离线时无法工作。
作为对照，评测员还对小部分任务并行测试了 doubao-seed-2.0-code。GLM-5.3 在多轮编辑中更擅长保留长文件状态，更适合体量较大的连续项目；doubao-seed-2.0 在孤立的局部函数级补全任务上更有优势。
本地托管的 GLM-5.3 在敏感专有代码工作负载上有数据隐私优势。但运营方必须为容器镜像版本管理、量化库兼容、持续运行时排障预留额外的运维成本。
## 四、对比汇总表与模型定位
| 评测项 | Step 5 Preview | DeepSeek V4 Pro | GLM-5.3 |
|---|---|---|---|
| 首轮可运行状态 | 完全可运行 | 完全可运行 | 含运行时错误，需人工修补 |
| 达到完整可玩所需轮数 | 2 | 3 | 4 |
| 大致人工修改行数 | 约 0 | 0-10 | 约 30 |
| 生成代码量 | 约 600 行 | 约 480 行 | 约 450 行 |
| 隐式产品体验意识 | 高 | 中 | 中 |
| 运维部署开销 | 低 | 低 | 高（本地推理栈维护） |
从这次实操基准可以归纳出三个差异化使用画像：
1. Step 5 Preview（工程循环导向）：最适合快速原型与 MVP 构建，能自主补齐大量隐式产品质量缺口，代价是偶尔生成冗余代码。
2. DeepSeek V4 Pro（稳定执行导向）：在已有精确需求清单时最理想，产出结构良好、易维护的代码，严格遵循显式指令，不过度发挥。
3. GLM-5.3（本地控制导向）：核心价值在于私有网络推理，不把专有源码发送给外部云 API。代价是更高的手工修复负担，以及 vLLM 技术栈的持续运维。
组织在多模型端点上做横向对比评测时，集中的访问管理能降低运维摩擦。Treerouter 这类统一 API 网关可整合多模型路由、凭据处理与调用日志，简化可重复的基准测试工作流。
## 五、结论
用琐碎的算法任务做基准，可能掩盖只有在移动软件工程综合约束下才会暴露的真实弱点。这套 Three.js Android 跑酷游戏测试，在三个模型都能生成语法合法代码的前提下，测出了它们之间有意义的行为差异。
Step 5 Preview 展现出强大的隐式产品意识，能以最少人工干预交付近乎完整可玩的结果。DeepSeek V4 Pro 在需求全面、结构良好的前提下，提供可靠、易维护的实现。自托管 GLM-5.3 经过人工修补后结果可接受，主要代价是复杂的本地基础设施维护，包括严格的 vLLM 镜像版本纪律。
没有单一模型在所有场景下普遍胜出。工程团队可采用混合工作流：用 Agent 导向模型做快速原型迭代，需求稳定后用指令忠实模型做生产级实现，隐私敏感的专有代码工作则部署本地开源权重模型。在目标硬件上做真实多特性测试仍然不可或缺，静态基准分数无法完全预测移动端的实际运行行为。
# GLM-5.3 API 接入指南：TreeRouter 统一接口调用与多模型切换实战
GLM-5.3 已在 TreeRouter 模型广场中提供。对于需要将智谱模型接入现有应用的开发者，关键不只是完成一次 API 请求，还包括统一接口配置、模型切换、异常处理以及 Token 成本控制。
TreeRouter 提供 OpenAI 兼容的 API 接入方式，并在模型广场中整合国内外 175+ 个模型选项。开发者可以使用一个 API Key 调用账户权限范围内的不同模型，减少分别维护多个服务商接入配置的工作量。
本文以 `glm-5.3` 为例，介绍实际请求代码、流式响应处理、模型切换和计费注意事项。
## 一、GLM-5.3 接口配置
根据 TreeRouter 模型详情页，GLM-5.3 的接口类型为 OpenAI 兼容格式，端点为 `/v1/chat/completions`。
| 配置项 | 参数 |
|---|---|
| API Base URL | `https://treerouter.com/v1` |
| Chat Completions Endpoint | `/chat/completions` |
| Model ID | `glm-5.3` |
| Authentication | Bearer Token |
| Request Format | JSON |
| 计费方式 | 按 Token 计费 |
请以控制台当前显示的模型标识、可用分组和接口文档为准。
## 二、Python 调用：使用 OpenAI SDK
如果项目已经使用 OpenAI Python SDK，可以通过调整 `base_url`、`api_key` 和 `model` 完成接入，无须为每个模型重新编写一套客户端。
```python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TREEROUTER_API_KEY"],
base_url="https://treerouter.com/v1",
timeout=60.0,
max_retries=2,
)
response = client.chat.completions.create(
model="glm-5.3",
messages=[
{
"role": "system",
"content": "You are a software engineering assistant."
},
{
"role": "user",
"content": (
"Review this API architecture and identify "
"potential reliability issues."
)
}
]
)
print(response.choices[0].message.content)
```
这段代码使用标准 Chat Completions 请求格式。`model` 必须与 TreeRouter 模型广场中的标识一致，`base_url` 则指向 TreeRouter 的统一 API 地址。
对于已有项目，通常只需要将客户端配置抽离为环境变量或配置文件，即可在不同部署环境中复用。
## 三、流式响应：适用于实时交互应用
对于代码助手、对话界面和实时生成任务，流式响应可以让客户端逐步接收模型输出，而不必等待完整回答生成后才展示结果。
如果 GLM-5.3 对应端点支持标准 Chat Completions 流式输出，可以使用以下写法：
```python
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["TREEROUTER_API_KEY"],
base_url="https://treerouter.com/v1",
timeout=60.0,
)
stream = client.chat.completions.create(
model="glm-5.3",
messages=[
{
"role": "user",
"content": "Explain the trade-offs of multi-model routing."
}
],
stream=True,
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if delta.content:
print(delta.content, end="", flush=True)
print()
```
该示例使用 OpenAI SDK 的流式处理方式。上线前应确认模型端点支持 `stream=True`，并检查是否存在特殊的响应字段或结束标记。
生产环境还需要处理客户端断开连接、请求超时和流式传输中断等情况，避免长时间占用连接资源。
## 四、Node.js 调用示例
对于 Node.js 项目，可以采用相同的 OpenAI 兼容接口：
```javascript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.TREEROUTER_API_KEY,
baseURL: "https://treerouter.com/v1",
timeout: 60000,
maxRetries: 2,
});
async function main() {
const result = await client.chat.completions.create({
model: "glm-5.3",
messages: [
{
role: "user",
content: "Explain how to design a reliable model-routing layer."
}
],
});
console.log(result.choices[0].message.content);
}
main().catch((error) => {
console.error("TreeRouter API request failed:", error.message);
process.exitCode = 1;
});
```
对于已经集成 OpenAI SDK 的应用，这种方式可以复用现有客户端结构。更换模型时，应同时检查目标模型的权限、支持的参数以及返回结构，不能假定所有模型的能力完全一致。
## 五、一 Key 多用：如何切换不同模型
TreeRouter 的一个核心特点是统一 API 接入。根据当前模型广场，平台覆盖国内外 175+ 个模型选项，包括智谱、DeepSeek、阿里巴巴、OpenAI、Anthropic、Google、Moonshot、MiniMax 和 xAI 等供应商。
在应用架构中，可以将模型名称作为独立配置，而不是将它固定在业务逻辑中。
例如：
```python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TREEROUTER_API_KEY"],
base_url="https://treerouter.com/v1",
)
def generate_answer(model: str, prompt: str) -> str:
response = client.chat.completions.create(
model=model,
messages=[
{"role": "user", "content": prompt}
],
)
return response.choices[0].message.content or ""
# 调用智谱模型
glm_answer = generate_answer(
"glm-5.3",
"Summarize the main risks of a distributed API system."
)
print(glm_answer)
```
如果需要切换到其他模型，只需将 `model` 替换为模型广场中实际可用的标识，并确认当前 API Key 具有对应权限。
这种设计适合需要比较不同模型输出、根据任务分配模型，或在测试阶段快速切换模型的应用。
需要注意：统一 API Key 并不意味着模型自动路由、自动故障切换或所有模型参数完全一致。具体路由和容灾能力应以平台实际提供的功能为准。
## 六、GLM-5.3 的价格与 Token 成本控制
根据 TreeRouter 模型广场提供的 GLM-5.3 模型详情页，当前展示的“一 Key 国产中转全模型”分组价格如下：
| 计费项目 | 截图显示价格 |
|---|---:|
| 输入 Token | $6.80 / 1M Tokens |
| 输出 Token | $23.80 / 1M Tokens |
| 缓存 Token | $1.70 / 1M Tokens |
以上是截图所示分组的价格，实际可用分组和扣费规则应以登录后的控制台为准。
按该价格进行简单估算，假设一次请求产生 2,000 个输入 Token 和 1,000 个输出 Token，且不涉及缓存计费：
- 输入费用：2,000 ÷ 1,000,000 × $6.80 = $0.0136
- 输出费用：1,000 ÷ 1,000,000 × $23.80 = $0.0238
- 合计：$0.0374
这只是按截图价格计算的示例，不代表每次请求的固定费用。
在生产环境中，可以通过以下方式控制成本：
1. 避免在每次请求中重复发送不必要的历史对话。
2. 根据任务需要控制输出长度，减少冗余生成。
3. 监控输入、输出和缓存 Token 的实际消耗。
4. 根据任务复杂度选择合适的模型，避免所有任务都使用同一个模型。
5. 定期核对控制台用量记录与应用日志，及时发现异常请求。
## 七、常见接入错误与排查方法
### 1. HTTP 401：认证失败
检查 API Key 是否正确，确认请求头是否包含：
```text
Authorization: Bearer YOUR_API_KEY
```
同时确认密钥没有过期或被撤销。
### 2. HTTP 403：权限不足
检查当前 API Key 的模型分组和调用权限。如果密钥没有获得目标模型的访问权限，需要在控制台确认分组配置。
### 3. HTTP 404：接口或模型标识错误
检查 Base URL 是否正确，避免重复拼接 `/v1` 或 `/chat/completions`。同时确认模型名称为 `glm-5.3`，而不是其他相近版本。
### 4. HTTP 429：请求受到限流
检查账户的请求限制、并发情况和服务端返回信息。可以根据服务端提供的限流提示实施退避重试，避免立即重复发送大量请求。
### 5. HTTP 400：请求参数不兼容
检查 JSON 格式、消息结构及模型支持的参数。不同模型可能对特定参数有不同要求。建议先使用最小请求验证接口，再逐项加入其他参数。
### 6. 请求超时或连接中断
检查网络连通性、超时设置和服务端响应状态。对于流式请求，还应处理连接断开和部分输出已经返回的情况。
排查时建议记录请求时间、HTTP 状态码、模型标识和服务端错误信息，但不要在日志中记录完整 API Key 或其他敏感凭证。
## 八、总结
通过 TreeRouter 接入 GLM-5.3，开发者可以使用 OpenAI 兼容接口完成基础调用，并在现有 Python 或 Node.js 项目中复用客户端结构。
对于需要同时使用不同模型的应用，TreeRouter 的一 Key 多用模式可以减少分别管理多套 API 接入配置的工作量。平台模型广场覆盖国内外 175+ 个模型选项，开发者可以根据模型能力、接口支持情况和实际 Token 成本进行选择。
实际部署时，建议先完成单次请求验证，再测试流式输出、错误处理和真实业务负载。模型名称、价格、权限和接口能力均应以当前控制台及对应文档为准。
**立即访问 TreeRouter 模型广场：**https://treerouter.com/pricing
