Xing4.0-29B-Intent 部署：29B 只跑 4B，命令抄哪条

客服工单进来一句「帮我查明天北京到上海的航班」，系统要知道两件事：这是不是一个已知意图，以及出发地、目的地、日期分别是多少。以前这活儿要么靠规则引擎硬写正则，要么塞给一个通用大模型再祈祷它别发挥。Xing4.0-29B-Intent 把两件事合并成一次推理：给定类别和字段定义，模型直接吐出 category + args。

本篇是把它在本地跑起来的完整操作手册，覆盖权重下载、服务启动、SDK 接入、效果验收、再训练和已知边界。仓库地址：github.com/XingChen-AGI/Xing4.0-29B-Intent

先说分工。站内另一篇《专用模型 58 分登顶：意图识别换赛道了》讲发布事件、榜单排名和路线之争，那篇把评测表逐列摊开。本篇不重复评测表细节，只解决命令行怎么敲、模型放哪、结果怎么验。

一、先搞清楚这模型解决什么

官方定位是「Schema 引导的意图识别与结构化信息抽取模型」。四个不相干的任务共用同一套输出协议：

输出统一是 JSON 数组，每项一个 category 加一组 args；没有可填参数时 args 是空数组。一句话命中多个类别，或同一类别有多组参数实例，都能靠这个结构表达。

所谓 Schema 引导，指类别和字段不是模型自己猜的，而是调用方给定：候选类别名、类别含义描述、每个字段的名字和抽取规则。开发者定义好这套，模型按定义填空，换个业务 Schema 就能切场景。

官方示例是「帮我查明天北京到上海的航班。」，配合「查询航班」类别和三个字段定义，期望输出：

查询航班
{'出发地': '北京', '目的地': '上海', '日期': '明天'}

「明天」被原样保留，没有翻译成具体日期。字段描述里写「保留原文」就是保留原文。

二、动手前的清单

模型仓库在 github.com/XingChen-AGI/Xing4.0-29B-Intent，Apache-2.0，2026-10-17 创建，10-19 最后推送，17 星 0 个开放 issue（GitHub API 实测）。

权重在 Hugging Face 上有三个官方仓库，这是 2026-10-22 通过 HF API 实测的体积：| 仓库 id | 形态 | 体积 | 用途 | |---|---|---|---| | XingChen-AGI/Xing4.0-29B-Intent | 41 个 safetensors 分片，dtype bfloat16 | 约 62.4 GB | 主版本，精度基线 | | XingChen-AGI/Xing4.0-29B-Intent-FP8 | 同样 41 个分片，FP8 | 约 33.2 GB | 显存吃紧时用 | | XingChen-AGI/Xing4.0-29B-Intent-GGUF | 单文件 xing4_0-29b-intent-iq4_nl.gguf | 约 17.8 GB | 消费级显卡、llama.cpp |

三个仓库的 license 都是 apache-2.0，ModelScope 上有同名同 id 镜像。没找到官方 AWQ 或 GPTQ 权重，量化路线就是 FP8 和 GGUF 两条。

宿主机要求照基座仓库的部署教程来：Docker 建议 24.0 及以上，NVIDIA 驱动建议 535 及以上，还要装 NVIDIA Container Toolkit。SDK 侧要求 Python 3.8 以上、httpx 0.24 以上。这里跟同期另一条线上的 DeepInfer 引擎要区分开：Python 3.12 干净虚拟环境是那个框架的要求，跟本文的 Xing4.0 部署无关。

许可这块要特别说一句：模型权重、公开数据、代码和 Python SDK 全部 Apache-2.0，商用友好。但数据集说明文档末尾写着，各公开源数据集的原有许可条款同样适用，商用前请核对源数据集的授权要求。别以为整套都是 Apache-2.0 就完事。

三、启动服务：命令在基座仓库，不在这个仓库

这是最容易卡住的一步。Intent 仓库的 README 没有给启动命令，只说一句「模型服务的环境准备与启动方式可参考基座模型的『服务化推理』说明」，然后让你把教程里的模型路径换成 Xing4.0-29B-Intent 权重路径，把 --served-model-name 设成 Xing4.0-29B-Intent，显存、并行度及上下文长度按实际环境配置。

命令去 github.com/XingChen-AGI/Xing4.0-29B-A4B 的 README「服务化推理」章节和 tutorial 目录抄。官方给了三个预编译 Docker 镜像，不用自己编译框架：

docker pull quay.io/xingchen-agi/xingchen-inference-vllm:v0.29.1rc1-xing4_0

这一行拉取集成好 Xing4.0 适配的 vLLM 镜像，同系列还有 xingchen-inference-vllm-ascend:v0.26.0rc1-xing4_0（昇腾）和 xingchen-inference-sglang:v0.5.20.rc1-xing4_0（SGLang）。

vLLM 路径的官方启动命令原文，把模型路径换成你的 Intent 权重目录：

vllm serve ${MODEL_PATH} \
    --host 0.0.0.0 \
    --port 8000 \
    --served-model-name Xing4.0-29B-Intent \
    --tensor-parallel-size 2 \
    --trust-remote-code \
    --max-model-len 262144 \
    --gpu-memory-utilization 0.90 \
    --max-num-seqs 4 \
    --enable-auto-tool-choice \
    --reasoning-parser xing4_0 \
    --tool-call-parser xing4_0 \
    --speculative-config '{"method":"mtp", "num_speculative_tokens": 1}'

模型名必须和客户端请求里的 model 字段一致，否则接口报模型不存在；--reasoning-parser 和 --tool-call-parser 都必须是 xing4_0，写别的名字解析器不认。

SGLang 路径的官方命令原文：

sglang serve --model-path ${MODEL_PATH} \
   --trust-remote-code \
   --host 0.0.0.0 \
   --port 8000 \
   --served-model-name Xing4.0-29B-Intent \
   --tp-size 2 \
   --context-length 262144 \
   --mem-fraction-static 0.90 \
   --max-running-requests 4 \
   --reasoning-parser xing4_0 \
   --tool-call-parser xing4_0 \
   --speculative-algorithm EAGLE

--tp-size 是 SGLang 的张量并行卡数，和 vLLM 的 --tensor-parallel-size 是同一件事，两边都得能整除可见 GPU 数。

如果不想用预编译镜像，官方还提供开源插件方式：vLLM 走 XingChen-AGI/xing4-vllm-plugin，SGLang 走 XingChen-AGI/xing4-sglang-plugin。插件以 Python 包分发，entry point 注册，容器里装一下就行：

pip install -e /workspace/xing4-vllm-plugin --no-deps

这行在容器内安装 vLLM 插件，--no-deps 避免插件连带替换容器里的 vLLM 本体。装完验一下 entry point 是否可见，输出里应包含 ('xing4_0', 'vllm_xing4_0_plugin:register')。

显存这件事官方怎么说？官方部署教程没有给出「至少需要多少显存」的硬指标，只在示例里用了 NVIDIA H100 单卡 80GB、两卡共 160GB 的环境，原文明确标注这「仅为演示与验证所用的硬件环境，并非强制要求」。命令里给出的可调项是 --gpu-memory-utilization 0.90（vLLM）和 --mem-fraction-static 0.90（SGLang）这类显存预留比例。官方给的 OOM 处理办法是三条：调低 --gpu-memory-utilization（如 0.85）或 --max-model-len（如 131072）、改用 FP8 版本模型、减少 --max-num-seqs。结论就是按实际环境配置。

这里有一处官方文档内部口径不一致，值得提前知道。vLLM 插件文档的常见问题里写着「mHC 模式（hc_mult > 1）仅支持 bfloat16」，并写明「FP16 或量化路径会报错」；而同一份文档的 OOM 小节又建议「使用 FP8 版本模型以减少显存占用」。这两个说法指向相反的操作，官方没有裁决，实际用哪个版本请在自己的环境上实测再定。

上游框架的支持状态也记一笔。官方 README 表格里列出四个适配 PR：SGLang 的 sgl-project/sglang#39793、NVIDIA/TensorRT-LLM#19283、llama.cpp 的 ggml-org/llama.cpp#29012、KTransformers 的 kvcache-ai/ktransformers#2168，全部标注「待合入」，各自还给了 commit hash。

四、SDK 接入：几行代码拿到结构化结果

SDK 在仓库的 XingIntentSDK 目录，从源码装：

cd XingIntentSDK
python -m pip install -e .

这行在仓库根目录执行，把 SDK 以可编辑模式装进当前环境。

最小可跑例子，官方 README 原文：

from xingintent import Arg, Intent, IntentClient

client = IntentClient(
    base_url="http://localhost:8000/v1",
    model="Xing4.0-29B-Intent",
    max_tokens=512,
)
result = client.predict(
    text="帮我查明天北京到上海的航班。",
    intents=[
        Intent(
            "查询航班",
            "查询指定日期与路线的航班",
            args=[
                Arg("出发地", "出发城市"),
                Arg("目的地", "到达城市"),
                Arg("日期", "用户提到的出行日期，保留原文"),
            ],
        )
    ],
)
print(result.category)
print(result.args)

Intent 三个参数是类别名、类别含义描述、参数列表；Arg 两个参数是字段名和字段说明。字段说明不是装饰，是给模型的抽取规则，写清楚边界比写漂亮有用。

result.category 返回首要类别，result.args 返回合并后的参数字典。多类别或多组参数实例必须遍历 result.intents，否则会丢结构：

for item in result.intents:
    print(item.category, item.args)

这里有个细节容易踩：result.args 只是首个意图的参数，同名冲突时后出现的值覆盖前面的。想保留全部参数实例，只能用 result.intents 里各项的 args，那是原始参数列表。

几个实用特性：Intent.fallback("其他意图") 造兜底意图，result.is_fallback 判断是否命中；guided_json=True 让 SDK 自动生成 JSON Schema 通过 response_format 传给 vLLM 走约束解码；AsyncIntentClient 是异步版；Schema.from_json("schema.json") 从文件加载 Schema；Dialog().human(...).ai(...) 拼多轮对话。异常分了类：APIError 对应网络或非 200 响应，ParseError 对应输出解析不出 JSON，ValidationError 对应返回的 category 不在 Schema 里。调试期把 debug=True 打开，日志会打出完整请求 body 和模型原始输出。

五、怎么判断跑对了

先说官方评测口径，免得把榜单分当业务指标。官方测试集是 6,000 条样本，取自 48 个公开数据集，覆盖四类任务。四类任务分值是各数据集字段值 Micro-F1 的宏平均，总分是四类任务分值的等权平均，百分制。官方两次强调：分值不等于业务准确率，类别分值不代表所有字段都正确。

对你的实际业务来说，唯一有意义的是自建回归测试。三步：

1. 从线上真实流量里抽一批带人工标注的句子，覆盖高频意图、长尾意图、含歧义的句子和纯闲聊。
2. 把业务 Schema 写成 JSON，用 Schema.from_json 加载，每条句子跑一遍 predict。
3. 用 json.loads 解析后按结构比对，不要按字符串逐字比对，逐字比对会把 JSON 键顺序差异算成错误。

跑之前还要对齐提示词约定。官方要求每次请求只发一条 role: "user" 消息，任务说明、Schema 和对话内容全部塞进这一条；Schema 用 json.dumps(schema, ensure_ascii=False) 序列化后原样填入，类别名和槽位键名禁止改写；测试标签和标准答案绝对不能进请求。单标签任务每条样本只允许一个类别对象，多标签任务（NER、RE、EE）才允许多个对象并列。改动任何一处都得重新验证。

六、数据与再训练

配套数据集是 XingChen-AGI/Xing4.0-29B-Intent-oss，Apache-2.0。按官方数据说明文档的口径：

每个任务的数字都在官方文档里：命名实体识别 823,000 条占 29.9%，关系抽取 905,000 条占 32.9%，事件抽取 56,000 条占 2.0%，意图识别与槽位填充 969,000 条占 35.2%。另外配套了 170 个以上意图、148 个槽位的智能助手标签集，可以直接当新项目的初始 Schema 再裁剪扩展。

想做业务微调，路径是现成的：数据统一成 category + args 格式，从开源数据按需采样，和自建业务数据按比例混合做 SFT。仓库里 data/build_examples.py 把样本拼装成训练和推理用的中间格式：

python3 data/build_examples.py --root data/General/test --save_path out/test/

这一行处理某个 split 下的全部数据集文件，每个数据集输出一个 examples 文件；--fmt json 改成数组格式，--max_samples N 取前 N 条做调试样例。详细的分布、Schema 字段定义和样例构建方式在 data/README_zh.md。

想找一把尺子量效果，可以看 CMPA-SLU。这是星辰实验室面向手机端智能交互场景构建的中文口语理解基准，仓库在 github.com/XingChen-AGI/CMPA-SLU，相关论文《CMPA-SLU: A Benchmark for Chinese Mobile Personal Assistant Spoken Language Understanding》已被 EMNLP 2026 录用。

七、为什么 29B 只激活 4B

MoE 的账在 config.json 里写得清楚，这是 Intent 权重的一手字段：

每层放 64 个路由专家，每来一个 token 只点 4 个，再加 1 个常驻共享专家，稠密前两层（first_k_dense_replace: 2）不做稀疏化。所以总参数 29B，单 token 实际参与计算的约 4B。

这里必须澄清一个常见误读：激活 4B 说的是计算量，不是显存占用。权重照样是全量 29B 常驻，bfloat16 权重 62.4 GB 就是这么来的。想省显存只能靠量化版本或者减上下文。注意力走 MLA 低秩（q 768、kv 512），配合 40 层和 3584 隐藏维度，这是 256K 长上下文能撑住的结构基础。

两个复现时必须留意的字段细节。第一，config.json 里 transformers_version 写的是 5.14.1，generation_config.json 里写的是 4.48.1，两处不一致，官方没给解释，复现时遇到加载行为对不上先怀疑这个。第二，max_position_embeddings 是 262144，也就是原生 256K，但官方同时写了实际可用长度取决于部署配置，命令里的 --max-model-len 262144 只是上限，真按 256K 分配 KV Cache 开销很重，官方给的降级建议就是调到 131072。

生成默认参数在 generation_config.json 里：temperature 1.0、top_p 0.95、repetition_penalty 1.05。基座 README 建议复杂推理和通用任务用这组，代码和智能体任务把 temperature 降到 0.8。SDK 侧发请求时用 temperature 0 和 chat_template_kwargs 关闭思维链，符合结构化抽取要确定性输出的场景。

八、边界、坑和许可

先收拢官方明示的边界。模型只对关键决策信息快速响应，不做长篇推理；具体业务效果需结合目标数据和 Schema 验证；分值不等于业务准确率。这三条都出自官方 README 和数据说明文档。

许可方面，模型权重、公开数据、代码（含 Python SDK）全部 Apache-2.0，仓库 LICENSE 原文已核。商用友好这两个字站得住，前面提过的源数据集条款核对别忘了。

社区 issue 方面，Intent 仓库目前 0 个开放 issue，没什么可引用的踩坑记录。基座仓库有 11 个 issue，多是文档和功能请求，其中编号 #4 标题是「希望增加国产化的配置要求」，至今仍是开放状态。这是社区诉求不是官方口径，但它说明一件事：昇腾等国产算力上的生产级配置参数，官方还没成文给出，需要按自己的集群实测。另外配置里能看到模型带 1 层 NextN 草稿头（num_nextn_predict_layers: 1），这正是官方启动命令里 --speculative-config 用 mtp 方法、--speculative-algorithm EAGLE 的前提；checkpoint 若没有这层草稿头，投机解码参数按官方说明去掉即可。

九、一份上线前检查单

• 权重来自官方三个仓库之一，license 是 apache-2.0
• 服务起来的标志：vLLM 日志出现 Uvicorn running on http://0.0.0.0:8000，SGLang 出现 The server is fired up and ready to roll!
• --served-model-name 与客户端 model 字段一致，都是 Xing4.0-29B-Intent
• 客户端只发一条 user 消息，Schema 用 json.dumps(schema, ensure_ascii=False) 原样填入
• 回归集按结构比对而非字符串比对
• 显存不够时依次试：降 --gpu-memory-utilization、降 --max-model-len、换 FP8 权重、减并发
• 多类别场景遍历的是 result.intents 而不是 result.args

FAQ

Q1：Intent 仓库的 README 里没有启动命令，是不是官方没写？ A：不是没写，是拆到了基座仓库。官方指向 Xing4.0-29B-A4B 的「服务化推理」章节和 tutorial 目录，那里给了 vLLM、SGLang、KTransformers 三条路线的命令、预编译镜像和参数说明。Intent 侧只要换模型路径、把 --served-model-name 设成 Xing4.0-29B-Intent。

Q2：29B 总参、只激活 4B，是不是单张消费级显卡就能跑？ A：这是两回事。激活 4B 省的是算力不是显存，权重仍然全量常驻。bfloat16 权重约 62.4 GB，要压到消费级显卡得用官方 GGUF 版本，约 17.8 GB。基座仓库的 llama.cpp 部署文档实测环境是 RTX 3090 24GB 单卡跑量化版，但那测的是基座模型，且 llama.cpp 的适配 PR 至今未合入主干。

Q3：官方说激活 4B，为什么显存要求还是按 29B 算？ A：因为 MoE 的专家权重全部要驻留在显存里，只是每个 token 只路由到其中 4 个 expert 做前向计算。官方部署文档没有给出硬性显存下限，只在示例里用了 H100 单卡 80GB 两卡共 160GB，并明确说这不是强制要求。

Q4：怎么确认模型跑对了，而不是返回一堆格式正确但内容错的 JSON？ A：格式对不等于业务对。官方评测口径是 6,000 条样本、48 个公开数据集、Micro-F1 宏平均、总分等权平均、百分制，官方自己强调分值不等于业务准确率。业务侧唯一有意义的验收是自建回归集：从真实流量抽样人工标注，按结构比对 category 和每个字段值，多类别场景要遍历 result.intents。

Q5：量化版本到底选 FP8 还是 GGUF？官方文档里两种说法冲突怎么办？ A：官方文档内部确实存在口径不一致，vLLM 插件文档一处写 mHC 模式仅支持 bfloat16、量化路径会报错，另一处 OOM 小节又建议用 FP8 版本减少占用，官方没有裁决。可行做法是先按 bfloat16 把链路跑通、拿到基准数据，再分别用 FP8 和 GGUF 量化版跑同一套回归集，用业务指标而不是省下的显存做决定。

延伸阅读

• AI agent 工具调用实战 SOP：让大模型学会调工具：AI agent 工具调用实战 SOP：让大模型学会调工具
• 上下文压缩实战：先剪工具输出，再摘要历史：上下文压缩实战：先剪工具输出，再摘要历史
• MiniCPM-V 4.7怎么跑：手机到电脑三条路：MiniCPM-V 4.7 怎么跑：手机到电脑三条路