用 MiniMax 云 API 生成推理模型蒸馏数据：reasoning-from-scratch 第 8 章 MiniMax 蒸馏脚本实战指南

示例工程【免费下载链接】reasoning-from-scratchImplement a reasoning LLM in PyTorch from scratch, step by step项目地址https://gitcode.com/gh_mirrors/re/reasoning-from-scratch点击查看免费下载本篇技术指南聚焦 reasoning-from-scratch 仓库第 8 章蒸馏数据生成模块中的MiniMax 专属托管生成脚本讲解如何借助 MiniMax 的 OpenAI 兼容云 API为 MATH 数学题批量生成教师模型回答作为后续训练小模型知识蒸馏的训练数据。读完本文你将掌握 MiniMax 平台账号与 API Key 的申请流程、MiniMax-M3 / M2.7 系列模型的选择、单条样例 / MATH-500 / 12,000 条 MATH 数据集三种规模的数据生成命令以及脚本底层温度钳制、重试退避、增量写入、断点续跑、并行请求等实现原理可直接上手复现完整的 MiniMax 蒸馏数据管线。一、背景MiniMax 在蒸馏数据生成中的定位在 第 8 章蒸馏数据生成模块 中仓库提供了三种教师输出生成途径本地 Ollama适合可本地运行的中小模型、OpenRouter 托管 API适合 DeepSeek R1 671B 等超大模型以及本文的主角MiniMax 托管 API。MiniMax 脚本与 OpenRouter 脚本的工作方式类似把 MATH 题目按固定提示模板包装后发给云端模型收集模型的思考流reasoning与最终回答写入与 Ollama / OpenRouter 完全一致的 JSON 结构。该脚本位于ch08/02_generate_distillation_data/other_providers/minimax/目录下generate_with_minimax.pyMiniMax 数据生成主脚本通过其 OpenAI 兼容 API 批量生成蒸馏答案README.mdMiniMax 专属使用说明即本文主体test_minimax_distillation.py脚本的单元测试与可选的真实 API 集成测试。运行前提所有命令都应在ch08/02_generate_distillation_data/目录下执行这样math_train_sample.json等相对路径才能按原样解析。二、MiniMax 平台准备使用脚本前需要完成三步在 MiniMax 开放平台注册账号在账号设置中生成一个 API Key将 API Key 保存在安全位置例如密码管理器脚本通过环境变量MINIMAX_API_KEY读取。脚本主入口会校验环境变量缺失时直接退出并提示见 generate_with_minimax.pyMiniMax API key missing. Set MINIMAX_API_KEY. Get your API key at: https://platform.minimaxi.com/可用模型一览README 给出的 MiniMax 可用模型如下模型名定位关键规格MiniMax-M3最新一代模型脚本默认值512K 上下文窗口最大输出 128KMiniMax-M2.7上一代模型1M 上下文窗口MiniMax-M2.7-highspeedM2.7 的高速变体面向高吞吐场景优化从脚本源码的--model参数帮助文本generate_with_minimax.py也可以看到这三个模型名被显式列出默认值为MiniMax-M3。三、快速上手用样例数据跑通流程先用仓库自带的 5 条样例数据做冒烟测试。在ch08/02_generate_distillation_data/目录下执行MINIMAX_API_KEYYOUR_API_KEY uv run other_providers/minimax/generate_with_minimax.py \ --math_json math_train_sample.json \ --dataset_size 5 \ --model MiniMax-M3 \ --num_processes 1 \ --out_file sample_minimax_outputs.json如果你不使用uv把uv run换成python即可例如python other_providers/minimax/generate_with_minimax.py ...。生成的输出文件结构与 Ollama、OpenRouter 脚本完全一致详见 主 README 的输入输出格式说明{ problem: ..., # 原始题目 gtruth_answer: ..., # 原始标准答案重命名自输入中的 answer message_thinking: ..., # 模型的思考流 message_content: ... # 模型的最终回答 }输入文件math_train_sample.json中的每个对象至少需要problem题目与answer标准答案两个字段多余的level、type、unique_id等键会被忽略可参考 math_train_sample.json 的实际结构。输出中的answer被改名为gtruth_answer是为了避免与模型的回答产生歧义。注意MiniMax 要求temperature必须落在(0.0, 1.0]区间内脚本会自动把超出范围的值钳制回合法区间详见第五节源码解读。命令行参数速查表以下参数均来自脚本的parse_args()定义generate_with_minimax.py供实际调参时参考参数类型默认值说明--dataset_sizeint500要评估/生成的样本数量--promptstrNone单条提示词模式跳过数据集直接对单条 prompt 请求并把一个 JSON 对象打印到 stdout--math_jsonstrNone可选的自定义 MATH JSON 文件路径省略时使用load_math500_test()默认下载的math500_test.json--modelstrMiniMax-M3MiniMax 模型名可选MiniMax-M3、MiniMax-M2.7、MiniMax-M2.7-highspeed--max_new_tokensint2048最大生成 token 数映射到 API 的max_tokens--temperaturefloat0.7采样温度MiniMax 要求(0.0, 1.0]0钳到 0.01、1钳到 1.0--top_pfloat1.0Top-p 采样参数--timeoutint600单次请求超时秒--max_retriesint3每个样本请求失败时的重试次数--retry_delayfloat3.0重试基础等待秒数指数退避--out_filestrNone输出 JSON 路径省略时按模型名生成默认文件名形如math500_minimax_m3_full_answers.json--verboseflag关闭打印每个样本的完整预测--shorter_answers_promptflag关闭使用要求简短解释的提示模板仍保留\boxed{ANSWER}最终答案格式--resumeflag关闭从已有输出文件断点续跑跳过已完成的行--num_processesint1并行 MiniMax 请求数1 表示顺序生成四、生成 MATH-500 蒸馏数据集若要为 500 道 MATH-500 测试题生成教师答案可以省略--math_json脚本会自动加载math500_test.json首次使用时下载并保存本地副本。从源码看load_math500_test()会先检查本地文件是否存在不存在时才从仓库的ch03/01_main-chapter-code/math500_test.json下载并落盘generate_with_minimax.py。MINIMAX_API_KEYYOUR_API_KEY uv run other_providers/minimax/generate_with_minimax.py \ --dataset_size 500 \ --model MiniMax-M3 \ --num_processes 1 \ --out_file math500_minimax_distill.json运行期间终端会通过reasoning_from_scratch.ch03.eta_progress_messagech03.py滚动显示进度与 ETA命令结束时打印耗时与写入行数。生成完毕后可以用 average_field_lengths_json.py 查看字段统计或用 第 3 章验证脚本 evaluate_json.py 计算教师模型准确率uv run average_field_lengths_json.py --json_path math500_minimax_distill.json uv run ../../ch03/02_math500-verifier-scripts/evaluate_json.py \ --json_path math500_minimax_distill.json \ --gtruth_answer gtruth_answer \ --generated_text message_content五、生成 12,000 条 MATH 蒸馏数据集这是第 6、7、8 章共用的、与 MATH-500 不重叠的 12,000 条 MATH 训练集。如果本地还没有该文件先下载curl -fL -o math_full_minus_math500.json \ https://raw.githubusercontent.com/rasbt/math_full_minus_math500/refs/heads/main/math_full_minus_math500.json然后执行大规模生成注意开启--resume与并行MINIMAX_API_KEYYOUR_API_KEY uv run other_providers/minimax/generate_with_minimax.py \ --math_json math_full_minus_math500.json \ --dataset_size 12000 \ --model MiniMax-M3 \ --num_processes 50 \ --resume \ --out_file math12000_minimax_distill.json对于这种大规模运行--num_processes需要根据你的 MiniMax 账号并发上限与期望吞吐量灵活增减。主 README 也提示顺序生成 12,000 条答案非常耗时--num_processes 50这类并行配置能大幅缩短运行时间主 README 中以 OpenRouter 场景为例给出了 100 小时缩短到约 2 小时的量级参考MiniMax 场景下的并行收益同理具体加速取决于账号并发限制。六、源码级原理脚本是如何工作的generate_with_minimax.py的可执行主流程if __name__ __main__块按以下顺序执行校验MINIMAX_API_KEY环境变量与--num_processes 1若指定--prompt走单条请求模式并打印 JSON 后退出确定输出路径未指定时用model_to_filename()根据模型名生成math500_safe_model_full_answers.json加载数据集并截取前--dataset_size条若--resume且输出文件存在读取已完成行并校验一致性先发送一条Reply with OK.的连通性探测请求打印Model ready顺序--num_processes 1或并行线程池生成剩余行每完成一行即增量写盘。6.1 温度钳制clamp_temperatureMiniMax 的合法温度区间是(0.0, 1.0]脚本通过clamp_temperature()统一处理generate_with_minimax.py 0钳到0.01 1钳到1.0。该行为在 test_minimax_distillation.py 中有 6 组单元测试覆盖并且集成测试还验证了钳制发生在请求发出之前捕获实际 payload 断言temperature 0.01。6.2 OpenAI 兼容 API 调用与指数退避脚本直接使用 Python 标准库urllib.request向https://api.minimax.io/v1/chat/completions发起 POST 请求generate_with_minimax.py请求体为 OpenAI 兼容格式{ model: MiniMax-M3, messages: [{role: user, content: 渲染后的提示词}], stream: false, max_tokens: 2048, temperature: 0.7, top_p: 1.0 }请求头使用Authorization: Bearer API_KEY。失败重试采用指数退避第 n 次重试前等待retry_delay * 2^(n-1)秒且封顶 60 秒generate_with_minimax.py可捕获的异常类型包括 HTTPError、URLError、TimeoutError、JSONDecodeError、IncompleteRead、RemoteDisconnected、ConnectionResetError 等网络与解析类错误重试耗尽后抛出带最后错误信息的RuntimeError。6.3 响应解析提取思考流与最终回答parse_minimax_response()兼容两种消息形态generate_with_minimax.pydict 形态读取message.content最终回答与message.reasoning_content思考流字符串形态直接把message当作content。如果content为空而reasoning_content非空脚本会把思考流回退填入content避免丢失回答两者都为空则抛出含响应结构信息的RuntimeError方便排查。返回值固定为{message_thinking: ..., message_content: ...}随后由generate_row()组装成带problem/gtruth_answer/message_thinking/message_content四字段的记录。6.4 提示模板保证 \boxed 答案格式脚本内置两套提示模板generate_with_minimax.py默认模板You are a helpful math assistant.\nAnswer the question and write the final result on a new line as:\n\\boxed{{ANSWER}}\n\nQuestion:\n{prompt}\n\nAnswer:--shorter_answers_prompt模板把要求改为Provide a short explanation, and then write the final result on a new line as:\n\\boxed{{ANSWER}}...用于生成更精简的思考过程同时保持\boxed{}最终答案格式不变——这是后续用evaluate_json.py验证教师准确率的前提。6.5 增量写入与断点续跑write_rows_json_incremental()每完成一个样本就把全部行写到一个.tmp临时文件再原子替换目标文件generate_with_minimax.py。因此中途中断也能保留已完成结果。load_resume_rows()兼容 JSON 数组以及含records数组的 dict 两种形态。validate_resume_rows()续跑前逐行校验——行数不能超过数据集、每行必须是 JSON 对象、必须含problem键、且第 i 行的problem必须与当前数据集的第 i 条完全一致generate_with_minimax.py防止换数据集后误续旧文件不匹配时会提示Use a different output file or disable --resume。6.6 并行生成--num_processes 1时脚本用concurrent.futures.ThreadPoolExecutor维护一个滑动窗口保持在飞请求数等于--num_processes每完成一批就按原始顺序把结果追加到输出并落盘乱序完成、顺序写入保证输出行序与数据集一致任一任务失败则取消其余 pending 请求并报告失败的行号generate_with_minimax.py。七、测试覆盖如何验证脚本行为仓库为 MiniMax 脚本提供了完整的自动化测试test_minimax_distillation.py不需要真实 API Key 即可运行大部分用例纯单元测试mock 网络不触发真实调用clamp_temperature的温度钳制边界0.0→0.01、-1.0→0.01、1.5→1.0、1.0 保持parse_minimax_response的标准响应、缺reasoning_content、thinking-only 回退、缺choices/ 空choices/ 非法格式 / 无内容抛错、message 为字符串等 10 种场景render_prompt两种模板渲染model_to_filename三个模型名的文件名生成如MiniMax-M3→math500_minimax_m3_full_answers.json增量写入、续跑文件解析与校验的各分支--help无报错运行。Mock HTTP 集成测试模拟成功响应、HTTP 500 触发重试直至失败、以及钳制后的温度确实进入请求 payload。真实 API 集成测试可选只有设置了MINIMAX_API_KEY环境变量才会执行pytest.mark.skipif分别验证MiniMax-M3与MiniMax-M2.7-highspeed的真实推理结果与generate_row的完整四字段输出。运行方式在仓库根目录uv run pytest tests/ -k minimax八、数据流向从蒸馏数据到模型训练MiniMax 脚本产出的 JSON 与 Ollama / OpenRouter 产物同构可直接被 第 8 章蒸馏训练脚本 消费。distill.py中的format_distilled_answer()distill.py会把message_thinking与message_content拼接为带think标签--use_think_tokens或不带标签的两种目标文本再与render_prompt(entry[problem])组成prompt_ids answer_ids训练样本。换言之MiniMax 云模型生成的思考流即成为小模型要蒸馏模仿的推理过程。这也解释了为什么脚本要专门解析reasoning_content字段——MiniMax 的思考流是蒸馏数据中信息量最大、最关键的组成部分。九、常见注意事项小结目录约束所有命令需在ch08/02_generate_distillation_data/下执行否则相对路径math_train_sample.json、math_full_minus_math500.json无法解析。API Key 安全仅通过MINIMAX_API_KEY环境变量注入不要写死在命令行或脚本里。温度范围MiniMax 合法区间为(0.0, 1.0]脚本会自动钳制若手工调试 API 请自行遵守该约束。断点续跑大规模生成务必加--resume换数据集前先确认输出文件已被清理或改名避免validate_resume_rows()的一致性校验失败。并发上限--num_processes受账号并发限制约束过高会触发服务端限流此时重试逻辑会启动指数退避需要按实际账号情况调整。成本与规模12,000 条全量生成耗时较长建议先用--dataset_size截取几百到一千条试跑主 README 亦建议截断大文件先小规模验证确认输出格式与准确率后再全量铺开。至此从 MiniMax 平台准备、三种规模的数据生成命令到脚本的温度钳制、重试退避、响应解析、增量落盘、断点续跑与并行调度原理再到测试验证与下游蒸馏训练的衔接你已经掌握了一条完整可复现的 MiniMax 蒸馏数据生产链路。赞分享示例工程【免费下载链接】reasoning-from-scratchImplement a reasoning LLM in PyTorch from scratch, step by step项目地址https://gitcode.com/gh_mirrors/re/reasoning-from-scratch点击查看免费下载相关推荐从入门到精通Plotly数据集应用终极指南 从入门到精通Plotly数据集应用终极指南 想要快速掌握数据可视化技巧吗Plotly数据集项目为您提供了丰富的真实世界数据资源这个开源数据集集合包含超强模型蒸馏LeetCode87的知识蒸馏方法超强模型蒸馏LeetCode87的知识蒸馏方法 你还在为海量LeetCode题目无从下手本文将带你探索如何通过知识蒸馏技术从LeetCode87项目中提取Llama 3模型蒸馏小模型知识蒸馏技术与实践Llama 3模型蒸馏小模型知识蒸馏技术与实践 引言大模型部署的困境与蒸馏解决方案 随着大型语言模型LLM如Llama 3的快速发展模型参数量从8B到人工智能大模型基础模型本地部署上一篇Voyager Image Refinement 深度解析用反向 Alpha 混合算法无损去除 Gemini 图片水印下一篇TDengine TSDB MCP Servermcp-tdengine-tsdb接入指南只读查询、元数据浏览与 AI 助手集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考