KAT-Coder-V2.5-Dev 开源模型全解析：35B MoE Agentic Coding 架构、后训练管线与多框架部署实践

KAT-Coder-V2.5-Dev 是快手 Kwaipilot 团队在 KAT-Coder-V2.5 之后发布的开放权重版本：以 Qwen3.6-35B-A3B 为基座、总参数量 35B 而仅激活 3B 参数的 MoE 模型，专为 Agentic Coding（智能体编程）场景设计。本文以仓库 README.md 为主线，结合 config.json、chat_template.jinja、tokenizer_config.json 等配置与源码级证据，完整讲解其基准性能、SFT+RL 后训练管线、四类推理框架的部署命令、Chat Completions 调用方式，以及 262K 原生上下文与 YaRN 超长文本扩展方案。读完本文，你将能直接上手部署并正确配置该模型的工具调用、思维保留与超长上下文能力。

模型概览与仓库构成

本仓库发布的是 KAT-Coder-V2.5-Dev 经后训练（post-training）后的模型权重，已转换为 Hugging Face Transformers 标准格式，可兼容 Hugging Face Transformers、vLLM、SGLang、KTransformers 等主流推理框架。需要特别说明两点（README 原话强调）：

• 仅含语言模型权重：本次开放权重发布只提供语言模型（text-only），视觉/多模态组件不包含且不可用；
• 模型类型为qwen3_5_moe，架构为Qwen3_5MoeForConditionalGeneration，训练精度为 bfloat16。

从 model.safetensors.index.json 可以验证权重结构：索引文件记录的total_size为 69,321,221,376 字节（约 69.3GB，与 35B 参数量的 bf16 存储相符），全部 13 个分片model-00000-of-00013.safetensors至model-00012-of-00013.safetensors的权重路径均以model.language_model.*为前缀——没有任何视觉塔（vision tower）权重，与 README 的 text-only 声明一致。仓库中 safetensors 与图片文件均为 Git LFS 指针（实体大文件需通过 LFS 拉取），但索引与配置足以确认模型结构。

核心架构参数（来自 config.json）

config.json 的text_config给出了语言模型的完整结构，关键参数如下：

值得注意的还有layer_types：40 层采用linear_attention 与 full_attention 交替的混合注意力设计，每 4 层插入一层 full attention（full_attention_interval: 4），其余为线性注意力层，这有助于降低长上下文推理成本。generation_config.json中的默认采样参数为do_sample: true、temperature: 1.0、top_p: 0.95、top_k: 20，EOS token 为 248046（<|im_end|>）/ 248044（<|endoftext|>），这些默认值与下文 API 示例中的参数一致。

版本亮点：性能提升与异常行为优化

README 将 KAT-Coder-V2.5-Dev 的核心收益归纳为两点：

• 性能提升：通过 SFT/RL 训练，官方在相似参数规模的模型群体中取得了 Agentic Coding 领域的 SOTA 结果（该表述为官方声明）；
• 异常行为优化：通过 RL 训练，两类病态行为得到显著抑制——异常工具标签（abnormal tool labels）从 9.34% 降至 0.28%（约 -9pp）；单轮连续重复（single-turn continuous repetition）从 0.34% 降至 0%。

这些异常行为的治理与后训练阶段专门设计的奖励项直接相关，详见下文"后训练管线"一节。

基准性能与评测方法

README 给出了 KAT-Coder-V2.5-Dev 在 7 项 Coding Agent 基准上与 7 个对照模型的完整对比（下表完整继承自 README.md，加粗列为该模型成绩）：

Terminal-Bench 2.1 的加粗数字为两个 agent harness 的平均值，小号数字为各 harness 单独得分（Terminus-2 / Claude Code）。

评测方法与配置（README 原注）

• 评测方法：表中所有指标均为官方在内部复现——下载公开模型权重，通过 vLLM 或 SGLang 部署，在统一的标准化流水线下评测；不直接采信各模型的官方报告值。每个模型在每个评测集上仅测试一次，仅在发现明显错误时重测。
• 评测配置：
  • SWE-bench Verified / Multilingual / Pro、KAT-Code-Bench：agent=claude_code@2.1.195，pass@k=1，temperature=1.0，top_p=0.95，256k ctx；
  • Terminal-Bench 2.1：agent=terminus-2 / claude_code，pass@k=1，temperature=0.7，top_p=1.0，256k ctx；
  • PinchBench：agent=openclaw@2026.3.13，pass@k=1，temperature=0.7，top_p=1.0，256k ctx；
  • Scicode：pass@k=1，temperature=0.6，top_p=1.0，256k ctx。
• 异常说明：Qwen3.6-35BA3B 在 SWE-bench 三个测试集上的复现结果与官方存在约 10pp 差距（官方认为是 harness 版本与测试集优化所致）；Qwen3.5-35BA3B 与 Gemma4-26B-A4B-it 在评测中频繁出现调用当前环境不支持的 MultiEdit 工具的幻觉；这些偏差源于模型工具偏好与评测 harness 允许工具集不匹配，而非模型本身能力缺陷。

后训练管线：SFT 与 RL 两阶段

README 明确交代了模型的训练来源：以广泛认可的 Qwen3.6-35B-A3B 为基座，整体沿用 KAT-V2.5 的后训练配方（数据构建、训练流水线、优化策略基本不变），分两个阶段进行：

1. SFT：在 127K 条样本上对基座进行监督微调；
2. RL：在 SFT 模型之上进行强化学习训练。

RL 阶段保留了 KAT-V2.5 验证过的四大技术设计：

1. Token-in-Token-out（TITO）一致性：保证 rollout 与训练阶段的 token 序列严格一致，避免因聊天模板、序列化或 tokenizer 行为差异造成的训练偏差；
2. 截断重要性采样（TIS）：缓解异步 rollout 带来的策略陈旧与 off-policy 问题，截断重要性采样权重，降低过大权重引发的方差与不稳定性；
3. 可靠的沙箱与验证器：系统性地检查沙箱与验证器的稳定性和正确性，防止执行超时、环境错误或验证器误判被当作模型失败而污染奖励信号；
4. 基于 harness 执行反馈的层次化奖励：从 harness 提供的细粒度执行反馈构建层次化奖励，使模型既能朝最终任务目标优化，又能在未成功的轨迹中获得有意义的进展奖励，提高失败样本的训练价值、提供更密集的奖励信号。

Qwen3.6 特异的奖励适配

Qwen3.6 的轨迹模式与 KAT-V2.5 阶段不同，需要额外的奖励适配。官方实验显示：初期使用简单的 0-1 二元奖励在第二个 epoch 就导致模型崩溃。轨迹分析发现，随着训练推进模型越来越倾向于在单轮内发出大量并行工具调用（偶发超过 70 个调用），导致上下文快速膨胀、大量无效轨迹与执行错误，最终破坏 RL 训练稳定性。

为此，官方在原层次化奖励之上补充了若干 Qwen3.6 特异的惩罚项（包括但不限于）：

• 单轮内过量的并行工具调用；
• 失败的工具调用；
• 空的工具调用块（empty tool-call blocks）；
• 大量重复内容。

这些针对性的奖励调整有效抑制了病态工具使用与重复生成，使 RL 训练稳定推进10 个 epoch，验证了整体训练管线与 Qwen3.6 特异奖励设计的有效性与可行性。

快速开始：四种推理框架部署

官方推荐通过 API 集成 KAT-Coder-V2.5-Dev，以下命令均创建http://localhost:8000/v1的 OpenAI 兼容端点。部署前务必记住：本次发布仅含语言模型权重（无 vision tower），多模态组件相关启动项需按各框架的纯文本模式处理。

SGLang（推荐 sglang>=0.5.10）

uv pip install sglang[all]

标准版本（8 卡张量并行，最大上下文 262,144 token）：

python -m sglang.launch_server \ --model-path Kwaipilot/KAT-Coder-V2.5-Dev \ --port 8000 \ --tp-size 8 \ --mem-fraction-static 0.8 \ --context-length 262144 \ --reasoning-parser qwen3

启用工具调用（增加工具解析器）：

python -m sglang.launch_server \ --model-path Kwaipilot/KAT-Coder-V2.5-Dev \ --port 8000 \ --tp-size 8 \ --mem-fraction-static 0.8 \ --context-length 262144 \ --reasoning-parser qwen3 \ --tool-call-parser qwen3_coder

注意：如果所用 SGLang 版本在加载时尝试构建多模态/视觉组件，会因缺少视觉权重而启动失败；此时应使用该版本的纯文本（language-model-only）选项（参见python -m sglang.launch_server --help）。

vLLM（推荐 vllm>=0.19.0）

uv pip install vllm --torch-backend=auto

注意：--language-model-only标志必填。它让 vLLM 跳过视觉编码器与多模态 profiling；不加该标志，vLLM 会尝试初始化 checkpoint 中不存在的 vision-tower 权重而启动失败。

标准版本：

vllm serve Kwaipilot/KAT-Coder-V2.5-Dev \ --port 8000 \ --tensor-parallel-size 8 \ --max-model-len 262144 \ --reasoning-parser qwen3 \ --language-model-only

工具调用版本：

vllm serve Kwaipilot/KAT-Coder-V2.5-Dev \ --port 8000 \ --tensor-parallel-size 8 \ --max-model-len 262144 \ --reasoning-parser qwen3 \ --enable-auto-tool-choice \ --tool-call-parser qwen3_coder \ --language-model-only

KTransformers

KTransformers 是面向 CPU-GPU 异构计算的 LLM 推理优化框架。使用 KTransformers 运行 KAT-Coder-V2.5-Dev 的步骤参见官方 KTransformers 部署指南（README 指引）。

Hugging Face Transformers

Transformers 内置轻量级服务器，适合快速测试与中等负载部署。需要最新版 transformers，并安装accelerate以支持多 GPU（分片）加载：

pip install "transformers[serving]" accelerate

启动服务（模型将自动放置到可用的加速器上）：

transformers serve Kwaipilot/KAT-Coder-V2.5-Dev --port 8000

通过 Chat Completions API 调用

环境准备

使用 OpenAI Python SDK（若未安装先升级），并按需配置环境变量：

pip install -U openai # 按实际环境设置 export OPENAI_BASE_URL="http://localhost:8000/v1" export OPENAI_API_KEY="EMPTY"

纯文本输入

from openai import OpenAI # 由环境变量配置 client = OpenAI() messages = [ {"role": "user", "content": "Type \"I love KAT-Coder-V2.5-Dev\" backwards"}, ] chat_response = client.chat.completions.create( model="Kwaipilot/KAT-Coder-V2.5-Dev", messages=messages, max_tokens=81920, temperature=1.0, top_p=0.95, presence_penalty=1.5, extra_body={ "top_k": 20, }, ) print("Chat response:", chat_response)

上述采样参数（temperature=1.0、top_p=0.95、top_k=20）与 generation_config.json 中的默认值一致。

Instruct（非思考）模式

KAT-Coder-V2.5-Dev 默认在回答前进行思考（thinking）。通过 API 参数可让模型直接输出而不思考：

from openai import OpenAI # 由环境变量配置 client = OpenAI() messages = [ {"role": "user", "content": "Write a Python function that returns the n-th Fibonacci number."}, ] chat_response = client.chat.completions.create( model="Kwaipilot/KAT-Coder-V2.5-Dev", messages=messages, max_tokens=32768, temperature=0.7, top_p=0.8, presence_penalty=1.5, extra_body={ "top_k": 20, "chat_template_kwargs": {"enable_thinking": False}, }, ) print("Chat response:", chat_response)

从 chat_template.jinja 可以看到该行为的实现：模板在生成 prompt 结尾（add_generation_prompt分支）中，当enable_thinking为 false 时只写入空<think>\n\n</think>\n\n，否则写入<think>\n引导模型展开推理。

保留历史思考（Preserve Thinking）

默认情况下，模型只保留处理最新一条用户消息时产生的思考块，形成常见的中插思考（interleaved thinking）模式。KAT-Coder-V2.5-Dev 额外训练了保留并利用历史消息思考痕迹的能力，可通过preserve_thinking选项开启：

from openai import OpenAI # 由环境变量配置 client = OpenAI() messages = [...] chat_response = client.chat.completions.create( model="Kwaipilot/KAT-Coder-V2.5-Dev", messages=messages, max_tokens=32768, temperature=0.7, top_p=0.8, presence_penalty=1.5, extra_body={ "top_k": 20, "chat_template_kwargs": {"preserve_thinking": True}, }, ) print("Chat response:", chat_response)

该能力对 Agent 场景尤其有价值：保留完整推理上下文可增强决策一致性，多数情况下还能通过减少冗余推理降低整体 token 消耗，同时改善 KV cache 利用率，在思考与非思考两种模式下均能优化推理效率。

从模板源码看，preserve_thinking的实际效果是：在渲染 assistant 消息时，若preserve_thinking为真（或该消息位于最近一次用户查询之后），则把<think>\n{reasoning_content}\n</think>块完整写回历史消息；否则只保留内容、丢弃思考块。这也解释了"interleaved thinking"的成因。

工具调用协议（chat_template.jinja 解析）

KAT-Coder-V2.5-Dev 的工具调用格式在 chat_template.jinja 中定义，且 tokenizer_config.json 为相关标记分配了独立 token：<tool_call>（248058）、</tool_call>（248059）、<tool_response>（248066）、</tool_response>（248067）、<think>（248068）、</think>（248069）。当消息中携带tools时，模板会在 system 消息中注入完整的工具说明，并要求模型仅以指定 XML 格式回复函数调用：

<tool_call> <function=example_function_name> <parameter=example_parameter_1> value_1 </parameter> <parameter=example_parameter_2> This is the value for the second parameter that can span multiple lines </parameter> </function> </tool_call>

协议要点（模板内置的<IMPORTANT>提示）：<function=...>块必须嵌套在<tool_call></tool_call>内；必需参数必须给出；可以在函数调用前（而非之后）用自然语言附带可选推理；若没有可用函数则正常作答且不提及函数调用。工具结果以<tool_response>...</tool_response>包裹并归入 user 消息。README 中"异常工具标签从 9.34% 降到 0.28%"正是针对这类调用格式的病态输出治理成果。这也解释了为何 vLLM / SGLang 启动命令中需要指定--tool-call-parser qwen3_coder：服务端解析器与模型训练时的模板格式必须严格对应。

处理超长文本：原生 262K 与 YaRN 扩展

KAT-Coder-V2.5-Dev 原生支持最长262,144 token的上下文（对应 config.json 的max_position_embeddings: 262144）。对于输入输出总长超过该限制的长程任务，README 推荐使用 RoPE 缩放技术（如 YaRN）处理，目前 transformers、vLLM、KTransformers、SGLang 均支持。启用 YaRN 有两种途径：

方式一：修改模型配置文件。将 config.json 中text_config.rope_parameters改为：

{ "mrope_interleaved": true, "mrope_section": [ 11, 11, 10 ], "rope_type": "yarn", "rope_theta": 10000000, "partial_rotary_factor": 0.25, "factor": 4.0, "original_max_position_embeddings": 262144 }

对比当前仓库 config.json 中的默认值（rope_type: "default"、无factor字段），可看到 YaRN 方案只是把rope_type切换为yarn并补充缩放因子factor: 4.0与原始最大位置original_max_position_embeddings: 262144，其余 mRoPE 参数保持不变——这保证了缩放前后位置编码的一致性。

方式二：命令行参数覆盖（无需改动配置文件）。

vLLM：

VLLM_ALLOW_LONG_MAX_MODEL_LEN=1 vllm serve ... --hf-overrides '{"text_config": {"rope_parameters": {"mrope_interleaved": true, "mrope_section": [11, 11, 10], "rope_type": "yarn", "rope_theta": 10000000, "partial_rotary_factor": 0.25, "factor": 4.0, "original_max_position_embeddings": 262144}}}' --max-model-len 1010000

SGLang 与 KTransformers：

SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 python -m sglang.launch_server ... --json-model-override-args '{"text_config": {"rope_parameters": {"mrope_interleaved": true, "mrope_section": [11, 11, 10], "rope_type": "yarn", "rope_theta": 10000000, "partial_rotary_factor": 0.25, "factor": 4.0, "original_max_position_embeddings": 262144}}}' --context-length 1010000

两处环境变量（VLLM_ALLOW_LONG_MAX_MODEL_LEN、SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN）用于显式允许服务端覆盖比原生 262K 更长的上下文长度限制，目标上下文 1,010,000 token 与factor: 4.0的缩放倍率相吻合。

引用与进一步阅读

若本文内容对你有帮助，可引用 KAT-Coder 技术报告（README.md 中的 Citation 条目，eprint 编号 2607.05471，2026 年 7 月发布）：

@misc{katcoder_v25_2026, title={{KAT-Coder-V2.5 Technical Report}}, author={{KwaiKAT Team}}, year={2026}, month={July}, eprint={2607.05471}, archivePrefix={arXiv}, primaryClass={cs.AI} }

如需进一步深入，可继续阅读仓库中的 README.md（官方原始说明与基准数据）、config.json（完整架构参数）、chat_template.jinja（聊天与工具调用模板实现）、tokenizer_config.json（特殊 token 定义）以及 generation_config.json（默认采样参数）。需要说明的是，本镜像中模型权重分片与图片为 Git LFS 指针文件，实际拉取需经由 LFS；且发布版本不含视觉组件，一切多模态相关配置（如vision_config、image_token_id）仅作架构占位保留。