企业官网建设流程全解析

我在内部工具链上跑了大半年单模型 Agent，最近把架构改成 Kimi K3 + Claude 双模型路由之后，成本降了差不多一个量级，代码生成和长文本分析的稳定性反而上来了。这篇文章就把这套 AI Agent 多模型路由的完整方案拆给你，包括为什么这么设计、环境怎么搭、路由逻辑怎么写、常见坑怎么排。适合正在做 Agent 开发的工程师，也适合刚接触 Claude Code 和 Kimi K3 的朋友照着一步步操作。

先说清楚一个概念：多模型路由不是什么高深算法，本质就是给 Agent 加一个调度层，把不同类型的任务分给不同模型。LLM 是大脑，Agent 是完整的执行系统，而路由层就是这个系统的调度中枢。下面直接进入正题。

1. 为什么做多模型路由：先搞清楚要解决什么问题

1.1 单一模型的瓶颈：质量、成本、速度不可能三角

很多团队一开始做 Agent 都习惯"一个模型打天下"，我自己也这么干过。选 Claude 就所有请求都走 Claude，选 Kimi K3 就全部走 Kimi K3。表面省事，实际上踩坑踩到怀疑人生。

单一模型至少有三个绕不开的问题。第一是成本浪费，最高端的模型处理摘要、抽取、改写这类简单任务，属于大炮打蚊子，钱花得冤枉。第二是质量不均衡，Claude 在代码生成和复杂工具调用上确实强，但面对超长中文文档的理解和结构化抽取，不一定比专门优化过的模型更划算。第三是稳定性，单点依赖意味着模型服务一抖动，整个 Agent 就瘫了。

我做个简单的算术你就明白成本差距有多大了。假设你的 Agent 每天处理 1 万个请求，其中 70% 是文本摘要、信息抽取、数据清洗这类常规任务，30% 是代码生成和重构。如果全部用高端模型，假设单价是低端模型的 8 到 10 倍，那一个月下来光推理费用就多烧掉一大截。这还没算高峰期限流带来的重试成本和工时要挟。

多模型路由解决的就是这个不可能三角：不追求一个模型在所有维度都最强，而是让最合适的模型处理最合适的任务。这不是炫技，是省钱省时间省头发。

1.2 Kimi K3 与 Claude 的能力画像

要设计路由策略，首先得摸清两个模型的底细。我把两个模型的实际表现整理成一张对比表，方便你对照自己的业务场景：

注意，Kimi K3 是开源权重模型，这一点对做私有化部署的团队是巨大优势。你可以在自己的机器上跑一个节点处理敏感数据，同时把代码生成这类任务路由到 Claude。既满足了数据合规要求，又保住了代码质量，这是很多企业选双模型路线的真实动机。

Claude 这边最大的杀手锏是 Claude Code 这个命令行 Agent 工具，它能把自然语言任务变成一连串的代码操作，配合 MCP（Model Context Protocol）协议接入各种外部工具，写代码、跑测试、改配置一条龙。这个生态是纯文本模型短期内很难追上的。

1.3 路由架构的总体方案选型

既然决定要双模型路由，接下来的问题是怎么路由。目前市面上有三条路：

第一条路是用现成的 API 网关，比如 LiteLLM，它可以把多家模型统一成 OpenAI 格式的出口，然后在网关上做模型分发。优点是改动小，缺点是路由逻辑比较简单，只能做基础的模型映射。

第二条路是用 Agent 框架内置的模型路由能力，比如 LangGraph 的节点选择机制。适合本身就在用框架的团队，但路由逻辑和框架强耦合，迁移成本高。

第三条路是自己写一个路由层，规则判断为主、模型分类为辅，配合统一网关落地。我最终选了这条路，原因是 Agent 的路由决策极度依赖业务上下文，比如任务类型、输入长度、是否需要调用工具、预算上限，这些门面框架给不了现成方案，自己写反而可控。

整体架构就是三层：业务输入先进路由层做决策，决策结果决定请求走哪个模型，所有模型统一挂在 LiteLLM 网关后面，通过标准 OpenAI 接口访问。这样换模型、加模型都不用在业务代码里大改，路由层改配置就行。

2. 环境搭建：Claude Code 与 Kimi K3 的接入

2.1 Claude Code 安装（Windows / Ubuntu 两条路）

动手搭环境，先从 Claude Code 开始。Claude Code 是 Anthropic 官方的命令行 AI Agent 工具，装好之后在终端里执行claude就能进入交互式编程助手，也可以作为自动化流水线的执行引擎调用。

在 Ubuntu 上安装很简单，前提是 Node.js 版本不低于 18，然后用 npm 全局安装：

node -v npm install -g @anthropic-ai/claude-code claude --version

如果claude --version能打印版本号，说明安装成功。在 Windows 上稍微麻烦一点，最常见的报错就是热搜里那句 "claude's workspace requires the virtual machine platform on windows. enable"。这个错误的意思是 Claude Code 的沙箱工作区依赖 Windows 的虚拟化功能，你需要先开启两个 Windows 功能：

1. 打开"控制面板 → 程序 → 启用或关闭 Windows 功能"
2. 勾选"虚拟机平台"（Virtual Machine Platform）
3. 勾选"适用于 Linux 的 Windows 子系统"（WSL）
4. 确定后重启电脑

重启之后确认功能已经生效，可以打开 PowerShell 执行：

wsl --status

看到 WSL 版本号就说明虚拟化平台已经可用了。更推荐的做法是直接在 WSL 的 Ubuntu 环境里安装 Claude Code，因为 Claude Code 很多底层操作依赖 Unix 风格的工具链，在 WSL 里运行最顺畅。装完 WSL 后，进入 Ubuntu 终端，再用上面那三条 npm 命令即可。

安装完成后需要认证，常见做法是把官方 API Key 写入环境变量：

export ANTHROPIC_API_KEY="你的密钥"

Windows 上可以在系统环境变量里新增同名变量。注意不要在公共仓库里提交密钥文件，本地项目根目录的.env文件要加进.gitignore。

2.2 Kimi K3 的接入方式

Kimi K3 是月之暗面开源的模型，接入方式有两条。第一条是直接走官方 API，因为兼容 OpenAI 接口格式，所以用任何支持 OpenAI 协议的 SDK 都能调用，只需要把base_url指到 Kimi 服务的地址。我用 Python 的 openai 库举个最小调用示例：

from openai import OpenAI client = OpenAI( api_key="你的Kimi_API_Key", base_url="https://api.moonshot.cn/v1" ) resp = client.chat.completions.create( model="kimi-k3", messages=[ {"role": "user", "content": "用三句话总结这份报告的核心结论。"} ], temperature=0.3 ) print(resp.choices[0].message.content)

先跑通这个最小示例很重要，它能确认网络连通性、API Key 有效性、模型名称三个基础要素都没问题。后面接入路由层之前，我强烈建议你先把这个脚本跑通，不然排查问题的时候会分不清是路由的问题还是模型接口的问题。

第二条路是本地部署开源权重。Kimi K3 的权重开放下载，适合对数据隐私要求高的场景。本地部署对硬件有要求，如果只是测试，一张 24G 显存的消费级显卡就能跑起来；如果要高并发服务化，那就需要多卡推理集群了。本地部署我用 vLLM 比较多，因为吞吐量高，部署命令大概长这样：

vllm serve kimi-k3-local \ --served-model-name kimi-k3 \ --port 8000

启动之后本地就有一个 OpenAI 兼容接口，地址是http://localhost:8000/v1。这也是后面 LiteLLM 网关可以直接挂载的入口。

2.3 用 LiteLLM 把两个模型放到一个出口

两个模型都通了之后，下一步是引入 LiteLLM 做统一网关。为什么要多这一层？因为你的 Agent 代码不应该关心"这个请求到底发给谁"，它只需要认准一个 base_url、一种请求格式就行。模型调度的事交给网关，业务代码保持干净。

LiteLLM 的配置文件是 YAML，我用下面的示例作为起点：

model_list: - model_name: claude-primary litellm_params: model: anthropic/claude-sonnet-4 api_key: os.environ/ANTHROPIC_API_KEY - model_name: kimi-k3 litellm_params: model: openai/kimi-k3 api_base: https://api.moonshot.cn/v1 api_key: os.environ/KIMI_API_KEY litellm_settings: drop_params: true

这里有个细节值得注意：Claude 的模型名加了anthropic/前缀，Kimi 的模型名加了openai/前缀。这是因为 LiteLLM 需要知道用哪个协议适配器去连上游，anthropic/走 Anthropic 原生协议，openai/走 OpenAI 兼容协议。写错前缀的典型症状是返回一堆协议解析错误。

配置文件保存为litellm_config.yaml，然后启动网关：

litellm --config litellm_config.yaml --port 4000

再用刚才的 openai 库测试，这次把 base_url 改成http://localhost:4000/v1，model 分别填claude-primary和kimi-k3，能正常返回就说明网关打通了。这一步做完，你的 Agent 只需要知道 localhost:4000 这一个地址。

2.4 VSCode 集成配置

开发 Agent 的过程中，我基本离不开 VSCode，所以顺手把 Claude Code 也集成进去了。官方提供了 Claude Code 的 VSCode 扩展，安装后在侧边栏就能直接打开会话面板，在编辑器里选中代码发送给 Claude 让它解释或修改，体验比切到终端再粘贴代码舒服得多。

扩展安装好之后，项目根目录下可以放一个.claude/settings.json做项目级配置，比如统一指定模型和权限策略：

{ "model": "sonnet", "permissions": { "allow": ["Read", "Edit", "Bash"], "deny": ["Write"] } }

我习惯把危险操作默认 deny，需要的时候在会话里单次授权。这个习惯帮我挡了好几次误删文件的悲剧，等会儿在排查章节里再细说。

3. 多模型路由核心机制实现

3.1 路由决策的四个维度

路由层不是简单地"看到代码就发 Claude，看到文本就发 Kimi"，在真实业务里，这种粗糙规则很快会被打脸。我总结下来，决策至少要参考四个维度：

• 任务类型：代码生成、代码审查、Debug 这类任务偏代码域；摘要、抽取、改写、知识问答偏文本域。这是最高优先级的维度。
• 输入规模：输入越长，对上下文处理能力要求越高，同时成本压力也越大。超长文本分析如果走高端代码模型，成本会失控。
• 工具需求：任务是否需要调用外部工具（执行 Shell、读文件、访问数据库）。复杂工具调用链路目前 Claude 更稳，Kimi K3 的函数调用能跑通，但复杂链路上我踩过坑。
• 预算与延迟约束：有些场景对延迟极其敏感，比如在线问答；有些场景是离线批处理，可以接受慢一点，只求便宜。路由参数里必须留这两个约束口子。

把这四个维度落成一张判断表，路由逻辑的骨架就出来了：

3.2 两级路由：规则优先 + 模型分类兜底

路由实现我建议做成两级：第一级是规则快速通道，第二级是模型分类兜底。规则通道的开销几乎为零，毫秒级完成；只有规则无法判断的模糊请求，才交给一个轻量模型做意图分类。

先看规则通道的 Python 实现：

# router.py from dataclasses import dataclass from enum import Enum class ModelRoute(str, Enum): CLAUDE = "claude-primary" KIMI = "kimi-k3" @dataclass class TaskProfile: task_type: str # code / text / analysis / chat input_len: int max_latency_ms: int need_tools: bool need_code_exec: bool def route_by_rules(profile: TaskProfile) -> ModelRoute | None: # 需要执行代码、调用工具 -> 走 Claude，工具调用链路更稳 if profile.need_code_exec or profile.need_tools: return ModelRoute.CLAUDE # 长文本、低成本文本任务 -> 走 Kimi K3 if profile.task_type in ("summarize", "extract", "rewrite") and profile.input_len > 3000: return ModelRoute.KIMI # 短文本、低延迟问答 -> 走 Kimi K3，便宜且快 if profile.task_type == "chat" and profile.max_latency_ms < 2000: return ModelRoute.KIMI return None # 规则无法判断，交给分类模型

规则通道返回None时，进入第二级。分类模型不需要很强大，直接用 Kimi K3 就够了，让它输出一个结构化标签：

def route_by_classifier(openai_client, prompt: str) -> ModelRoute: sys_prompt = """ 你是一个任务路由分类器。根据用户请求判断任务类型。 只输出一个单词：code / text / analysis / chat。 规则： - 涉及编写、修改、解释代码，输出 code - 涉及摘要、改写、抽取、翻译，输出 text - 涉及数据分析、报告解读、逻辑推理，输出 analysis - 以上都不明确，输出 chat """ resp = openai_client.chat.completions.create( model="kimi-k3", messages=[ {"role": "system", "content": sys_prompt}, {"role": "user", "content": prompt}, ], temperature=0, max_tokens=10, ) label = resp.choices[0].message.content.strip().lower() task_type_map = { "code": ModelRoute.CLAUDE, "analysis": ModelRoute.CLAUDE, "text": ModelRoute.KIMI, "chat": ModelRoute.KIMI, } return task_type_map.get(label, ModelRoute.KIMI)

注意分类模型的两个参数：temperature=0保证输出确定性，max_tokens=10防止它啰嗦。这一步虽然简单，但把规则覆盖不到的边缘情况兜住了。我实测下来，两级路由整体的准确率超过 95%，误判主要出现在那种"既要写代码又要分析结果"的复合任务上，这种场景我干脆默认走 Claude，因为代码能力是稀缺资源。

3.3 成本与延迟的量化对比

路由方案上线之前，最好先做一轮量化测算，不然你没办法向团队说明收益。成本公式很简单，单次任务成本 = 输入 token 数 × 输入单价 + 输出 token 数 × 输出单价。我用一个示例帮你建立体感，数字按常见定价假设，你可以替换成实际报价重新算。

假设一个文本摘要任务，输入 8000 token，输出 800 token。高端模型假设每百万输入 token 15 元、输出 75 元，Kimi K3 假设每百万输入 token 2 元、输出 8 元。算下来：

• Claude：8000/1000000 × 15 + 800/1000000 × 75 = 0.12 + 0.06 = 0.18 元
• Kimi K3：8000/1000000 × 2 + 800/1000000 × 8 = 0.016 + 0.0064 = 0.0224 元

单次看着没感觉，一天处理 10 万次这样的任务，差价就是一万五千多块一个月。这就是为什么我说路由不是优化，是刚需。延迟方面，Kimi K3 本地部署响应也快，基本在 1 到 2 秒量级；Claude 在复杂代码生成上会慢一些，但代码任务的用户容忍度本来就高，这个取舍是合理的。

3.4 回退与兜底策略

任何路由方案都必须考虑上游故障。模型服务不可能永远不挂，真正可靠的系统靠的是回退链。我设计的回退策略分三层：

第一层是超时回退。主模型调用超过阈值，比如 10 秒没响应，自动切换到备用模型重试。例如代码生成任务主路由是 Claude，超时后可以暂时降级到 Kimi K3，虽然代码质量可能有下降，但总比任务直接失败好。

第二层是异常回退。遇到限流（429）、服务不可用（5xx）时，记录错误后切换备选模型，并做指数退避重试。这里要注意，重试不能无限重试，一般最多 3 次，防止雪崩。

第三层是质量兜底。输出结果如果为空、被截断、或者检测到关键错误关键字，可以选择用另一个模型重新生成一次。这一层成本高，我只在代码生成这种高价值任务上启用。

回退逻辑用 Python 写一个装饰器或者包装函数都行，核心是每个请求都必须带model和fallback_model两个字段，统一由网关外的策略层控制。

4. 实战：搭建一个带路由的 AI Agent

4.1 Agent 整体结构与 Skill / Memory / MCP 设计

环境通了、路由逻辑有了，现在把它们组合成一个真正的 Agent。我先给 Agent 画个结构，一个能稳定跑起来的 Agent 通常有四个部分组成：任务规划器（Planner）、模型路由层（Router）、工具执行器（Tool Executor）、记忆模块（Memory）。

很多人分不清 LLM 和 Agent 的区别，其实一句话就够：LLM 是大脑，Agent 是装了这个大脑并配了手和脚的完整系统。Agent 除了调模型，还要会拆解任务、调用工具、记住上下文。而 MCP（Model Context Protocol）就是统一"手和脚"的协议，比如 Claude Code 通过 MCP 连接 Git、连接数据库、连接浏览器，这些都是 Agent 的工具。

Skill 和 Memory 也绕不开。Skill 是给 Agent 预置的操作技能文档，比如"如何安全地重构代码""如何生成标准 SQL"，Agent 在需要时读取这些技能说明，照着执行。Memory 是 Agent 的长期记忆，可以简单理解为一个带检索的向量数据库，存之前的对话摘要和项目偏好。MCP 则负责把这些记忆和工具以标准接口暴露给 Agent。

4.2 将 Claude Code 作为执行引擎，Kimi 做分析与预处理

实战方案我采用分工制：Claude Code 作为代码执行引擎，Kimi K3 做分析预处理。这样设计不仅是因为能力差异，还因为 Claude Code 的优势在"动手"，而 Kimi 的优势在"看图说话"。

一个典型的代码审查任务流程是这样的。第一步，Agent 把待审查代码的 README、目录结构、关键文件清单交给 Kimi K3，让它生成一份代码概览和风险点清单。第二步，路由层把风险点清单和完整代码块交给 Claude Code，让它执行详细的代码审查、定位具体文件并给出修改建议。第三步，Claude Code 修改代码后，Agent 调用测试工具跑一遍测试，把测试结果再交给 Kimi K3 做回归分析。整个流程下来，两个模型各干各的拿手活，效率比单模型高不少。

我写了一个简化的 Agent 主循环，路由层在这里承担关键调度的角色：

def run_agent(task_desc: str): # 第一步：分析任务，生成执行计划 plan = call_model(ModelRoute.KIMI, [ {"role": "system", "content": "你是任务规划器，输出执行步骤列表"}, {"role": "user", "content": task_desc}, ]) # 第二步：每个步骤走路由决策 for step in parse_steps(plan): profile = build_profile(step) target = route_by_rules(profile) or route_by_classifier(client, step) result = call_model(target, step) # 根据步骤类型决定是否调用工具 if profile.need_tools: result = execute_tool(step, result) log_router_event(step, target, result)

这个循环看着简单，但把路由、规划、执行、日志都串起来了。每个步骤都会打日志，后面排查问题全靠这些日志。

4.3 路由日志与可观测性

路由层上线之后，最重要的事就是记录每一次路由决策。我遇到不少团队不重视这一步，结果模型效果波动时根本说不清是模型问题还是路由问题，只能瞎猜。

日志至少需要记录这几个字段：请求 ID、任务类型、输入长度、路由目标模型、路由依据（规则还是分类）、延迟、成本估算、是否触发回退、最终状态。我用 JSONL 格式落盘，每行一条记录，方便后续用 jq 或者 Pandas 分析。关键代码：

import json, time def log_router_event(profile, route, response_meta, status="ok"): event = { "ts": time.time(), "task_type": profile.task_type, "input_len": profile.input_len, "route": route, "reason": "rule" if route else "classifier", "latency_ms": response_meta.get("latency_ms"), "cost_estimate": response_meta.get("cost"), "status": status, } with open("router_events.jsonl", "a") as f: f.write(json.dumps(event, ensure_ascii=False) + "\n")

我通常先让路由层跑两周，收集到足够的日志之后再统计：哪些任务类型经常被路由到哪个模型、误判集中在哪类请求、哪些请求触发了回退。然后拿着统计数据去调规则阈值，这样调整才有依据。你也可以把日志直接接入现有的监控系统，比如 Grafana 或者 Prometheus，但 JSONL 这个最小方案足够让路由策略迭代起来。

5. 常见问题与排查技巧实录

5.1 Windows 虚拟化平台报错处理

这应该是 Windows 用户遇到最多的拦路虎，报错原文是 "claude's workspace requires the virtual machine platform on windows. enable"。我第一次遇到还以为是要装什么第三方软件，后来查了官方文档才明白：Claude Code 在 Windows 上需要依赖虚拟化功能来运行沙箱工作区。

处理步骤我前面已经写过了，这里再强调几个细节。第一，开启"虚拟机平台"和"WSL"两个功能之后必须重启，不重启大概率还是不生效。第二，如果改了功能还是报错，可以打开 PowerShell 执行dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart，用命令行强制开启，再重启一次。第三，建议直接把 Claude Code 装在 WSL 里，绕开 Windows 原生环境的各种权限问题。

5.2 claude 命令无法识别

"claude : 无法将"claude"项识别为 cmdlet、函数、脚本文件或可运行程序的名称"这个报错，通常是 npm 全局安装路径不在系统 PATH 里。npm 安装的全局命令默认会放到一个 bin 目录，但 Windows 的 PATH 不一定包含它。解决方法是先执行npm config get prefix拿到全局目录，然后把对应的 bin 路径加入系统 PATH 环境变量，重新打开终端再试。

Ubuntu 上同样会遇到类似问题，可以执行export PATH="$(npm config get prefix)/bin:$PATH"临时生效，或者写进~/.bashrc永久生效。另外一个常见问题是 Node.js 版本太低，Claude Code 要求 Node 18 以上，执行node -v检查一下，版本不够就用 nvm 切换。

5.3 MCP 连接与工具调用失败

Agent 在调用 MCP 工具时失败，最常见的两个原因。第一个是 MCP Server 依赖的库没装全，比如某些 MCP Server 需要 Python 环境或者额外的 npm 包，漏装就会在启动时静默失败。排查方法是直接手动启动一次 MCP Server，看有没有报错。

第二个是环境变量没传进去。很多 MCP Server 需要自己的 API Key，而你在启动 Agent 时的环境变量并没有透传给它，导致工具调用时鉴权失败。解决方法是确认 Agent 的启动配置里有env字段，把 MCP Server 需要的密钥显式写进去。还有一个我自己踩过的坑：MCP Server 的启动命令用了npx，但 npx 在非交互式 shell 里找不到，解决办法是用绝对路径或者先手动安装再调用。

5.4 路由误判与回复质量下降

路由上线跑一段时间后，一定会碰到误判。症状是某些请求明显应该走 Claude 却走了 Kimi，或者反过来。排查误判的方法是回看路由日志，找到请求 ID，确认路由依据是规则还是分类模型，然后针对性地调整。

如果是规则误判，直接改规则条件就行，比如某些代码域关键词没覆盖到，补充进去。如果是分类模型误判，先看看分类用的提示词是否表达清楚，我建议在分类提示词里加上典型示例，Few-shot 的方式能显著提升分类准确率。比如明确写"涉及 import、function、class 关键字的请求归为 code"，这样 Kimi 分类时会更有依据。

如果发现某类请求频繁回退，那可能是路由规则的优先级设计有问题。比如你的规则把所有带工具需求的请求都发给了 Claude，但有些工具调用 Kimi 也能完成且更快，这时候可以把工具类型再细化，只把复杂工具链路发给 Claude。路由策略不是一锤子买卖，是需要根据线上数据持续调优的。

5.5 其他高频报错速查

我把我遇到过的其他问题整理成一个速查表，方便你直接对着排查：

最后有一个坑我必须单独拎出来说：权限配置。我一开始在 Claude Code 的settings.json里面把 Bash 权限全部设成了 allow，结果有一次 Agent 在执行清理任务时误删了一个临时目录里的文件，虽然没造成大事故，但教训足够深刻。现在的做法是默认 deny，需要运行命令时在会话中单独确认，或者只会放行白名单里的安全命令。做 Agent 开发，安全永远比效率优先，尤其是让模型自己操作终端的时候。

说实话，多模型路由这套方案并没有太多深不可测的技术，难的是想清楚任务画像、做好路由维度设计、再把日志体系建立起来持续迭代。我个人在实际操作中的体会是：先别追求复杂的路由策略，把规则通道和日志跑通，让数据告诉你哪个模型在哪个场景真正赚回了成本，再逐步加分类模型和回退策略。最后再分享一个小技巧，路由规则一定要留配置开关，用配置文件而不是硬编码来管理模型白名单和阈值，这样每次调整策略，都不用重新发版，几秒钟就能生效。