企业官网建设流程全解析

edge0 Python API 完全手册：3 行代码完成本地 MoE 推理，采样参数逐一讲透

【免费下载链接】Edge0项目地址: https://gitcode.com/gh_mirrors/ed/Edge0

edge0 是一个面向 Apple Silicon 的 Python 本地 MoE 推理框架：通过 MLX 后端 + SSD 专家按需卸载，让你用 3 行代码就能在自己的 Mac 上跑起 35B 稀疏 MoE 大模型（edge0-35b / edge0-8b），内存占用只由"激活专家集合"决定，而非参数量。本篇手把手带你完成安装、写出第一行推理代码，并把 temperature、top_p、top_k 等采样参数逐一讲透。

环境准备：2 步搭好本地 MoE 推理环境 🚀

先克隆仓库再安装（以下命令均在python/目录执行）：

git clone https://gitcode.com/gh_mirrors/ed/Edge0 cd Edge0/python python3.12 -m venv .venv && .venv/bin/pip install -e '.[dev,fetch]'

然后用官方脚本拉取模型（一个目录里同时包含基座权重和 LoRA / prerouter 适配器，下载即可用）：

.venv/bin/python scripts/fetch_models.py --tier edge0-8b --target-dir models .venv/bin/python scripts/fetch_models.py --tier edge0-35b --target-dir models export EDGE0_8B_MODEL=$PWD/models/edge0-8b

💡 小提示：如果看到乱码、混杂多种语言的输出，说明mlx版本过旧，执行pip install 'mlx==0.30.6' 'mlx-metal==0.30.6'即可。

3 行代码完成第一次本地 MoE 推理

edge0 采用 transformers 风格 API：AutoEngine.from_pretrained会根据模型目录下的config.json自动识别档位，并自动装配 prerouter 路由预测、Recover-LoRA 适配器和 SSD 专家卸载，你不需要逐层搭建。

from edge0 import AutoEngine from edge0.server.chat import ChatMessage, ChatRequest, ChatSession engine = AutoEngine.from_pretrained("/path/to/model") # ① 构建引擎（自动装配） req = ChatRequest(model=engine.name, messages=[ChatMessage(role="user", content="Hello!")], max_tokens=64) # ② 组装请求 tokens, meta = ChatSession(engine, req).run() # ③ 生成 print(engine._tok.decode(tokens)) engine.close() # 释放 mmap / 专家缓存

就这么简单。仓库里的 examples/demo.py 走的正是这条路径——edge0 demo命令执行的也是同样代码，可以直接对照阅读。ChatSession会自动完成分词、chat 模板渲染（含思考模式开关）与生成，返回(tokens, meta)，其中meta附带 token 用量统计与耗时。

想不想看看它背后发生了什么？核心机制共三个（详见 docs/architecture.md）：

• SSD 专家卸载：专家权重从存储按需流式读入，峰值内存被激活专家集合限制；
• Prerouter：训练好的小头提前一步预测专家路由，让专家加载与正向传播重叠，解码吞吐最高可提升 59%；
• Recover-LoRA：int4 基座冻结，用 FP 教师蒸馏训练的 LoRA 适配器找回量化损失，且保持不合并。

采样参数逐一讲透 🔍

所有采样行为集中在两个文件：config.py 定义GenerationConfig数据类，sampling.py 实现采样器sample()。每个请求可通过ChatRequest覆盖默认值（见 chat.py 的gen_config()，请求级参数优先级高于档位默认值）。

temperature：温度旋钮，0 即贪心

默认0.7。logits 会先除以 temperature 再 softmax：

• 调大（>1）→ 分布更"平"，输出更随机、更有创意；
• 调小（→0）→ 分布更"尖"，输出更保守、确定性更强；
• 设为 0（或负数）= 贪心解码：无论种子如何，永远取 argmax，这是与 HuggingFace / llama.cpp 一致的生产语义（见 sampling.py）。

top_p：核采样（nucleus）

默认0.95，小于 1.0 才生效。算法把 logits 从高到低排序做累积 softmax，截断到累积概率首次 ≤ top_p 的候选集合，其余置为-inf。top_p 越大候选越多：0.9 更聚焦、0.98 更发散。

top_k：硬性候选上限

默认64。只保留概率最高的 k 个 token，其余全部屏蔽。与 top_p 可叠加使用——实现顺序是temperature → top_k → top_p（见 sampling.py），即先按 k 截断，再做核采样。

repetition_penalty：抑制复读机

默认1.0（关闭）。采用 HF 风格的"带符号"惩罚：对已生成历史 token 的 logit，正值除以惩罚系数、负值乘以惩罚系数（sampling.py），且用向量化方式批量处理，避免逐 token 的 host 同步。长对话里建议设1.1~1.2，能有效减少"车轱辘话"。

max_tokens 与 eos_ids

• max_tokens：本次请求生成上限，默认档位值为512；
• eos_ids：命中即提前停止生成的 token 集合。

seed：可复现的随机数

sample()支持传入seed固定随机状态（sampling.py）——同样的 logits + 同样的 seed 必得同样的 token，方便对比实验与回归测试。

first_token_greedy：生产级小开关

默认True。首 token 强制贪心：思考块开头若随机采样到坏 token，整段回复会跑偏甚至进入"!!!"循环；强制首 token 取 argmax 是经过生产验证的防翻车模式（见 config.py 的注释）。

参数速查表

采样器行为均有单元测试覆盖，可参考 tests/test_sampling.py 中的用例（如temperature=0恒取 argmax、seed确定性、top-k 截断等）。

实测性能参考（Mac mini M4 Pro, 24 GB）📊

"冷"指进程启动后首个请求（专家权重从 SSD 换入），"热"指后续请求（页缓存命中）。你可以用 examples/bench.py 在自己机器上复测。

不想写代码？CLI 一键启动与 OpenAI 兼容接口

edge0 demo edge0-8b # 一条命令出结果 edge0 chat edge0-8b --prompt "用一句话解释流式推理" edge0 serve edge0-8b # 启动 OpenAI 兼容服务 :8000

serve启动后，任何 OpenAI SDK 都能直接对接（单模型单进程队列生成，逐 token SSE 流式返回）：

curl http://127.0.0.1:8000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"edge0-8b","messages":[{"role":"user","content":"Hello!"}],"max_tokens":32}'

核心源码与文档速查 📁

总结：edge0 Python API 把"MoE 大模型上端侧"的复杂工程收敛成了 3 行代码——AutoEngine自动装配一切，你要调的只有采样参数。装好环境、from_pretrained一把梭，剩下的就是按上表微调 temperature / top_p / top_k，让输出既快又稳。

【免费下载链接】Edge0项目地址: https://gitcode.com/gh_mirrors/ed/Edge0