企业官网建设流程全解析

Step-5-Preview Agent应用实战：构建长时程自主编程与金融分析助手的完整教程

【免费下载链接】Step-5-Preview-BF16项目地址: https://ai.gitcode.com/hf_mirrors/stepfun-ai/Step-5-Preview-BF16

Step-5-Preview 是 StepFun 面向 Agent（智能体）工作负载打造的旗舰大模型：600B 总参数、27B 激活参数、最高 1M token 长上下文，在长时程自主编程与金融分析任务上表现突出。本教程基于 Step-5-Preview-BF16 权重仓库，带你从零跑通离线推理，并一步步搭建属于你自己的 Agent 编程助手与金融分析助手。

一、认识 Step-5-Preview：为什么它是 Agent 场景的旗舰选择

Agent 应用和普通对话机器人最大的区别，在于它要长时间自主干活：反复调用工具、执行代码、检查结果、再来一轮。这对模型提出了三重考验——

从 config.json 可以看到关键规格：92 层解码器、352 个路由专家、每个 token 激活 top-8 专家，上下文上限 1048576 token。这套"混合专家（MoE）+ 稀疏注意力"的组合，正是它能在超大代码库上持续工作的原因。

💡 本仓库是BF16 精度的完整权重（24 个权重分片 + 视觉编码器 + MTP 层），另有配套的独立推理实现，见 inference/README.zh.md。

二、快速上手：3 步跑通 Step-5-Preview 离线推理

第 1 步：克隆仓库并安装依赖

git clone https://gitcode.com/StepFun/Step-5-Preview-BF16 cd Step-5-Preview-BF16/inference python3 -m venv --system-site-packages .venv && source .venv/bin/activate python -m pip install -r requirements.txt

依赖版本范围非常友好：torch>=2.10,<2.14、transformers>=4.57.6,<6等，见 inference/requirements.txt。

第 2 步：权重分片转换（只需一次）

多卡推理前，先用 inference/convert.py 把原始权重切成按进程（rank）分配的分片。BF16 完整模型推荐双节点 16 卡（TP=EP=16），每卡参数约 74.93 GiB：

python3 convert.py \ --checkpoint "<BF16权重目录>" \ --tp-size 16 --ep-size 16 --check-only # 先检查权重名称与形状 python3 convert.py \ --checkpoint "<BF16权重目录>" \ --out-dir "<分片输出目录>" \ --tp-size 16 --ep-size 16 # 生成 16 份分片 + tokenizer_files/

转换会产出tp16/model-r{rank}.safetensors与对应的config-r{rank}.json，供下一步直接加载。

第 3 步：启动生成（generate.py）

分片就绪后，在两台节点上分别用torchrun拉起 8 个进程（共 16 卡），每条命令都包含各自的NODE_RANK：

torchrun --nnodes=2 --nproc-per-node=8 \ --node-rank="$NODE_RANK" \ --master-addr="$MASTER_ADDR" --master-port="$MASTER_PORT" \ generate.py \ --tp-dir "<分片输出目录>/tp16" --ep-size 16 \ --prompt "请介绍一下张量并行。" \ --max-new-tokens 128

generate.py 支持三种输入：--prompt文本（默认套一层单轮对话模板）、--prompt-json精确 token 列表、--prompt-json-batch打包批量请求；多模态场景可加--image-inputs传入预处理后的图像张量。模型本体的张量并行/专家并行执行逻辑在 inference/model.py，稀疏注意力、MoE 等核心算子在 inference/kernel.py。

三、构建自主编程 Agent：长时程任务怎么做

工具调用协议：一个 JSONSchema 就能看懂

Step-5-Preview 的对话模板 chat_template.jinja 原生支持工具调用：你只需在请求中声明 JSONSchema 格式的工具列表，模型就会以结构化的tool_call块返回函数名与参数，执行结果再用tool_response角色回传，形成"调用 → 观察 → 再调用"的闭环。这正是长时程 Agent 的核心循环。

1M 长上下文：它为什么"读得下整个仓库"

看 config.json 中的注意力设计，Step-5 采用了巧妙的混合方案：

• 滑窗注意力：92 层中每 4 层安排 1 层"全注意力"，其余层只关注 512 token 窗口；
• 稀疏注意力（DSA）：全注意力层通过索引器从历史中选出最相关的 512 个区域（topk=512，见 config.json），避免对百万级历史做完整注意力计算。

这套组合让"通读一个大型代码库 → 跨文件修改 → 运行验证 → 迭代修复"这样的长流程成为可能，而不必担心上下文装不下。

调优建议：3 个官方推荐参数

官方给出的推荐推理设置是：temperature=1.0、top_p=0.95、top_k=0，并在 High 推理档位下评测。部署时记得加上--reasoning-parser step5与--tool-call-parser step5两个参数，模型才会正确输出思考内容与工具调用结构。

四、金融分析助手实战：图表、文档与量化推理

官方评测中，金融方向是 Step-5-Preview 的重点强化领域：它擅长把量化推理与财务报表、图表、截图等多模态材料结合起来，产出结构化分析报告。

视觉理解：47 层视觉编码器如何看图

多模态部分由 inference/vision_encoder.py 实现，关键配置见 config.json：47 层、width 1536、16 个注意力头，728×728 主图输出 169 个视觉 token，504×504 裁剪图输出 81 个——也就是说一张带细节裁剪的报表截图约消耗不到 1000 个 token，在 1M 上下文里非常"便宜"。图像占位符为 token ID 128001（<im_patch>），见 config.json。

一个典型工作流：从报表截图到结构化结论

1. 喂材料：把财报截图（主图 + 局部裁剪图）与文本要求一起传入；
2. 读图表：视觉编码器在 prefill 阶段把图像编码为特征，注入文本序列；
3. 做推理：模型结合长上下文中的制度说明、历史数据做多轮量化推理；
4. 出报告：以结构化格式输出分析结论，必要时调用工具核对数据。

想回归验证多模态链路是否完整，可运行python -m pytest -q test_vision.py，覆盖配置、权重加载到图文生成，见 inference/test_vision.py。

五、部署为服务：vLLM / SGLang 一键接入 OpenAI 兼容 API

如果你需要把模型提供给团队使用，官方支持用vLLM或SGLang起一个 OpenAI 兼容服务。硬件配置速查（摘自 README.md）：

服务就绪后，像调用任何 OpenAI 接口一样发请求即可（以 vLLM 为例，端口18000）：

curl http://127.0.0.1:18000/v1/chat/completions \ --header 'Content-Type: application/json' \ --data '{ "model": "step5", "messages": [{"role": "user", "content": "Hello!"}], "max_tokens": 4096, "stream": true }'

接入现有 Agent 框架时，通常只需把 base URL 指到该地址，工具调用能力随模板自动生效。

六、目录导览与常见问题

仓库关键文件导览

常见问题（FAQ）

Q1：BF16 和 FP8 版本有什么区别？FP8 是量化版，单节点 8×H200 即可跑通，更省显存；BF16 是原始精度，需要双节点 16×H200。convert.py只切分权重、保留原精度，不会把 BF16 量化成 FP8。

Q2：为什么 BF16 需要 16 卡？92 层完整 BF16 模型在 TP=EP=8 下每卡参数约 144.41 GiB，超出单卡上限；TP=EP=16 时每卡降到约 74.93 GiB，实测图文生成峰值约 76.37 GiB/卡，见 inference/README.zh.md。

Q3：离线推理路径支持哪些功能？当前独立实现支持贪心生成（文本与图文），尚未提供动态批处理、分页 KV 缓存和投机解码；服务化部署请走 vLLM/SGLang，那里功能更完整。

Q4：多模态输入怎么准备？用对应 checkpoint 的 processor 预处理图像，保存为 safetensors（pixel_values、可选patch_pixel_values/num_patches），再与含图像占位 token 的prompt-ids.json一起传给--image-inputs和--prompt-json，细节见 inference/README.zh.md。

七、总结

Step-5-Preview 用"600B MoE + 1M 长上下文 + 原生多模态 + 内置工具调用协议"，正好踩中了 Agent 应用最需要的四个点：

1. 自主编程：通读大仓库、跨文件修改、运行验证的长时程闭环；
2. 金融分析：量化推理 + 报表图表理解，输出结构化报告；
3. 部署灵活：离线torchrun直接跑，或 vLLM/SGLang 起 OpenAI 兼容服务；
4. 上手可控：convert.py转一次、generate.py跑起来，三步走通。

跟着本教程，你可以先在自己机器上验证推理链路，再逐步把它接进你的 Agent 工作流——这就是构建长时程编程与金融分析助手的完整路径。

【免费下载链接】Step-5-Preview-BF16项目地址: https://ai.gitcode.com/hf_mirrors/stepfun-ai/Step-5-Preview-BF16