如何快速上手d1a-e2b-it-qat-4bit：3步完成安装并跑通第一个决策请求（完整教程）
【免费下载链接】d1a-e2b-it-qat-4bit项目地址: https://ai.gitcode.com/hf_mirrors/mlx-community/d1a-e2b-it-qat-4bit
d1a-e2b-it-qat-4bit 是一款运行在Apple Silicon上的4-bit 量化 AI 决策模型：给它一段情境描述和几个问题，它只需一次前向传播，就会为每个选项返回校准后的概率，而不是生成一段文本。它基于MLX框架与 Gemma 4 E2B-it QAT 权重，支持决策、聊天以及照片/语音/视频多模态输入。本文带你3 步完成安装，并跑通第一个决策请求。
一、它是什么？为什么说"决策模型"很不一样 🧠
普通大模型靠"生成文字"回答问题，而 d1a-e2b-it-qat-4bit 的工作方式是：
输入 = 一段状态描述（state）+ 若干问题（questions，每个问题是 是/否、多选 或 打分） 输出 = 每个选项一个校准概率，一次前向传播完成，答案必然落在有效选项内
这意味着它的输出可解释、可比较、可接入自动化流程（比如给 PR 自动打标签、给工单做路由分派）。
| 项目 | 说明 |
|---|---|
| 主干模型 | Gemma 4 E2B-it QAT（276 个 int4 线性层与 Google 官方 QAT 权重逐位一致） |
| 量化 | 4-bit（group size 32），嵌入层 4-bit（group size 64），反量化误差 0.0 |
| 参数量 / 体积 | 约 46 亿参数，主模型约2.7 GB |
| 决策适配器 | LoRA（rank 16，约 97 MB），未合并，可随时关闭 |
| 多模态编码器 | 视觉 + 音频编码器（bf16，约 1.0 GB），在 media/ 目录 |
| 校准温度 | 1.55（拟合得到，ECE 从 0.064 降到 0.018） |
| 授权 | Apache-2.0 |
细节可见仓库说明 README.md。
二、仓库结构速览：先认清每个文件 📁
| 文件 / 目录 | 作用 |
|---|---|
| model.safetensors、model.safetensors.index.json | 4-bit 主干权重（2.7 GB，约 46 亿参数） |
| adapter/ | 决策用 LoRA 适配器；adapter/adapter_config.json 中 rank 16、alpha 32 |
| head.safetensors | 指针头（pointer head），用于输出选项概率 |
| d1a_config.json | 决策配置：校准温度、leading tokens、量化参数等 |
| config.json | 模型架构与量化配置（Gemma4 文本 + 视觉 + 音频） |
| generation_config.json | 聊天模式的采样参数（temperature 1.0、top_k 64、top_p 0.95） |
| media/ | 视觉/音频编码器及配套处理器配置 |
| tokenizer.json、chat_template.jinja | 分词器与聊天模板 |
💡 适配器是"未合并"的：关掉适配器，这个权重就是 Gemma 4 E2B-it QAT 本身，也能正常聊天——一份权重，两种用法。
三、3 步完成安装（macOS / Apple Silicon）🍎
第 1 步：安装 d1a 服务包
d1a 是承载该模型的推理框架，需要安装带serve、mlx、media三组扩展的版本（需支持其 issue #261 之后的开发版）：
pip install "d1a[serve,mlx,media]"第 2 步：获取模型文件（二选一）
- 方式 A（推荐）：不手动下载，第 3 步用模型名
mlx-community/d1a-e2b-it-qat-4bit让服务启动时自动拉取； - 方式 B：直接克隆仓库镜像，本地磁盘预留约4 GB（主模型 2.7 GB + 编码器 1.0 GB + 适配器 97 MB）：
git clone https://gitcode.com/hf_mirrors/mlx-community/d1a-e2b-it-qat-4bit第 3 步：启动本地推理服务
python -m d1a.serving.serve --run mlx-community/d1a-e2b-it-qat-4bit --port 8009使用本地克隆时，把--run参数换成你的本地目录即可。服务默认监听localhost:8009，启动后提供三个端点：
| 端点 | 用途 |
|---|---|
/v1/systemone | 决策请求（文本） |
/v1/systemone/media | 多模态决策（照片/语音/视频） |
/v1/chat/completions | 聊天（OpenAI 兼容格式，支持流式） |
四、跑通第一个决策请求：/v1/systemone ✅
一个决策请求由两部分组成：state（发生了什么）和questions（每个问题给出类型与候选项）。用 README 里的官方示例：
curl -s localhost:8009/v1/systemone -H 'content-type: application/json' -d '{ "state": "Shoes arrived two weeks late and in the wrong size. Also I see two charges on my card.", "questions": {"team": {"type": "choice", "instructions": "Which team should handle this?", "criteria": {"returns": null, "shipping": null, "billing": null}}} }'返回结果会给出每个选项的校准概率（官方示例在 Apple M1 Max 上约109 ms返回）。你也可以在 Python 进程内直接调用：
from d1a import D1A model = D1A.load("mlx-community/d1a-e2b-it-qat-4bit") answer = model.decide(state, questions)五、进阶玩法：多模态决策与聊天 📸💬
照片 / 语音 / 视频决策
同一个请求加上media字段，发到/v1/systemone/media：
curl -s localhost:8009/v1/systemone/media -H 'content-type: application/json' -d '{ "media": {"type": "image", "data": "'"$(base64 -i parcel.jpg)"'"}, "questions": {"damaged": {"type": "noul", "instructions": "Is the parcel damaged?"}} }'支持的多模态类型：
| type | 格式 | 限制 |
|---|---|---|
image | JPEG / PNG / WebP | — |
audio | WAV / FLAC / OGG | ≤ 30 秒 |
video | MP4 / MOV / WebM | ≤ 32 MB，均匀采样 16 帧（不用音轨） |
聊天模式
聊天时会自动关闭决策适配器，此时它就是 Gemma 4 E2B-it QAT 本身，走标准 OpenAI 格式：
curl -s localhost:8009/v1/chat/completions -H 'content-type: application/json' -d '{ "messages": [{"role": "user", "content": "Name three things to check when a parcel arrives damaged."}] }'采样参数见 generation_config.json。
六、关键配置解读：d1a_config.json 里的几个重点 ⚙️
打开 d1a_config.json 可以看到几个值得留意的字段：
temperature: 1.55——在 3178 条校准数据上拟合的校准温度，让输出的概率"说真话"（交叉验证 ECE 从 0.064 降到 0.018）；leading_ids: [2]——模型训练时每条记录以 token 2（<bos>）开头，d1a 框架会自动补上；如果你自己编码请求，必须手动前置它；adapter: "unmerged"——适配器未合并，这也是它能兼顾决策与聊天的原因；quantization——4-bit、affine 模式，线性层 group 32，嵌入层 group 64，与 config.json 中的quantization_config一一对应。
七、上手限制与避坑指南 ⚠️
- 问题必须用英文；文档内容可以是英文或日文；
- 该版本在未训练过的任务类型（transfer-v4）上比 v0.6 低 5.2 分。如果你的业务远离 D1A 自身任务（PR 标签、路由、难决策），建议锁定
JohnP1/d1a-e2b-it@v0.6； - 媒体能力目前仅在 14 个演示请求上做过零样本验证，正式使用前建议自行回归测试；
- 项目仍标记为实验性，接入 Agent 工具调用时需经过 D1A 的 fail-safe 阈值（
d1a.agents.presets.advise）。
结语
到这里，你已经在自己的 Mac 上跑通了一个4-bit 量化决策模型：一次前向传播、每个选项一个可信概率、还能看照片听语音。d1a-e2b-it-qat-4bit 相比上一代快了约 11%，体积只有 2.7 GB——想让大模型"做判断"而不只是"写答案"，这就是一个很好的起点。下一步可以试试把/v1/systemone接入你的工单系统或 PR 流水线，体验校准概率带来的确定性。
【免费下载链接】d1a-e2b-it-qat-4bit项目地址: https://ai.gitcode.com/hf_mirrors/mlx-community/d1a-e2b-it-qat-4bit
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
