harshatheg/Qwen-2.5-1B-RLCD · Hugging Face

来源：https://huggingface.co/harshatheg/Qwen-2.5-1B-RLCD

适用于Apple Silicon的并行约束解码

在 Spaces 中打开 (https://huggingface.co/spaces/drinkmoonshine/parallel-constrained-decoding)

在线演示：在 Hugging Face Spaces 上实时体验并排对比：drinkmoonshine/parallel-constrained-decoding (https://huggingface.co/spaces/drinkmoonshine/parallel-constrained-decoding)。

一个基于 MLX 的高吞吐量推理引擎，用于在 Apple Silicon 上进行结构化信息提取、决策路由和分类。

并行约束解码能够同时评估多字段 JSON 模式，而非顺序生成 token。在 Apple Silicon M4 Max 上，与标准自回归解码相比，它实现了5.6 至 7.0 倍的延迟降低，同时保证 100% 的模式有效性和经过校准的字段级置信度分数。

性能基准测试（Apple Silicon M4 Max）

使用 mlx-community/Qwen2.5-1.5B-Instruct-4bit 在 macOS Sequoia 上评估：

为什么选择并行约束解码？

自回归结构化生成的难题

标准的 LLM 结构化生成（如 JSON 模式或语法引导采样）依赖于逐 token 的自回归解码：

[上下文提示] -> "{" -> "\n" -> " " -> "risk" -> ":" -> " " -> "HIGH" -> ...
（需要 150 到 500 次顺序前向传递）

每个 token 都需要一次独立的 GPU/NPU 前向传递和顺序内存带宽往返。随着模式大小的增长，延迟与输出 token 长度成线性比例：

T_{\text{autoregressive}} = \sum_{k=1}^{K} t_{\text{step}}(k)

此外，自回归解码容易出现语法退化、字段遗漏和幻觉键。

解决方案：通过 KV 缓存广播实现并行评估

在结构化提取和分类中，字段值属于有界的候选集（布尔值或分类枚举）。并行约束解码利用了这一特性：

+---> [字段 1: "risk_level"] ------> Logit 切片 -> 首选
                          |
[上下文前缀预填充] -------+---> [字段 2: "requires_review"] --> Logit 切片 -> 首选
（单一 KV 缓存状态）      |
                          +---> [字段 M: "action_tier"] ------> Logit 切片 -> 首选
                          
                     （所有字段同时被评估）

1. 单一广播预填充：上下文文档和语义模式描述被一次性预填充到 MLX 键值（KV）缓存中。
2. KV 缓存广播：KV 缓存被并行广播到所有 M 个模式字段。
3. 子词表 Logit 切片：对于每个字段，仅评估属于有效模式选择的候选 token ID。其余词表被屏蔽。
4. 校准的 Softmax 概率：在候选切片上计算精确的归一化概率：P(c_i) = \frac{\exp(z_i / T)}{\sum_{j=1}^{C} \exp(z_j / T)}
5. Token 树消歧：当候选选择共享多 token 前缀词根时，引擎使用切片的缓存状态执行后续步骤，无需内存重新分配。
6. 程序化组装：输出 JSON 直接由经过验证的值构建，保证 100% 的语法有效性，不会出现 JSON 解析错误。

安装

先决条件

• Apple Silicon Mac（M1、M2、M3、M4 系列）
• macOS 14.0 或更高版本
• Python 3.10+

设置

克隆仓库并安装依赖：

git clone https://github.com/your-org/parallel-constrained-decoding.git
cd parallel-constrained-decoding

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

开发者 SDK 快速入门

1. 定义模式

模式使用 StructuredSchema 定义。每个字段指定一个 type（enum 或 boolean）、一个用于指导模型推理的 description，以及 choices（对于枚举类型，最多支持 255 种选择）：

from core.schema import StructuredSchema, FieldDefinition

# 选项 A：基于字典的定义
schema_dict = {
    "priority": {
        "type": "enum",
        "choices": ["P0_CRITICAL", "P1_HIGH", "P2_NORMAL", "P3_LOW"],
        "description": "基于客户业务影响的紧急程度等级"
    },
    "requires_escalation": {
        "type": "boolean",
        "description": "是否需要立即通知值班工程师"
    },
    "department": {
        "type": "enum",
        "choices": ["BILLING", "INFRASTRUCTURE", "SECURITY", "PRODUCT_SUPPORT"],
        "description": "目标处理部门"
    }
}

schema = StructuredSchema(schema_dict)

您也可以使用 FieldDefinition 显式构建字段：

fields = {
    "tariff_classification": FieldDefinition(
        name="tariff_classification",
        field_type="enum",
        description="协调制度 6 位关税类别代码",
        choices=["0101.21", "0101.29", "8471.30", "8517.12", "8542.31", ...] # 最多 255 种选择
    )
}

2. 运行并行生成

在您的上下文字符串上执行并行约束推理：

from core.engine import run_parallel_generation

context = """
事件报告：生产数据库 db-primary-01 CPU 使用率达 100%。
支付网关对 40% 的结账请求失败。
受影响的一级企业客户：Acme Global。
"""

result = run_parallel_generation(context, schema)

print(f"延迟：{result['elapsed_ms']} ms")
print(f"预填充时间：{result['prefill_ms']} ms")
print(f"传递次数：{result['sequential_forward_passes']}")
print("\n提取的 JSON：")
print(result["parsed_json"])

3. 响应结构

输出字典提供结构化 JSON 和详细的字段遥测数据：

{
    "mode": "parallel_constrained_calibrated",
    "elapsed_ms": 74.5,
    "prefill_ms": 52.1,
    "suffix_eval_ms": 18.2,
    "sequential_forward_passes": 1,
    "is_valid_json": true,
    "schema_match": true,
    "parsed_json": {
        "priority": { "value": "P0_CRITICAL", "prob": 0.9924 },
        "requires_escalation": { "value": "true", "prob": 0.9981 },
        "department": { "value": "INFRASTRUCTURE", "prob": 0.9815 }
    },
    "field_telemetry": {
        "priority": {
            "value": "P0_CRITICAL",
            "confidence": 0.9924,
            "cardinality": 4,
            "top_choices": [
                { "choice": "P0_CRITICAL", "probability": 0.9924 },
                { "choice": "P1_HIGH", "probability": 0.0068 },
                { "choice": "P2_NORMAL", "probability": 0.0006 },
                { "choice": "P3_LOW", "probability": 0.0002 }
            ]
        }
    }
}

4. 流式自回归基线对比

与标准自回归生成进行比较：

from core.engine import stream_naive_generation

for event in stream_naive_generation(context, schema):
    if event["type"] == "token":
        print(event["token"], end="", flush=True)
    elif event["type"] == "done":
        print(f"\n完成，耗时 {event['result']['elapsed_ms']} ms")

交互式 Web 可视化工具

仓库包含一个用于并排比较延迟和准确性的 Web 界面。

启动 Web 服务器：

bash run.sh

或使用 uvicorn 直接运行：

python3 -m uvicorn server.app:app --host 0.0.0.0 --port 8000

在浏览器中打开 http://localhost:8000。

功能特性

• 并排比较：并行约束解码 vs. 自回归流式生成。
• 实时毫秒计时器：实时显示已用延迟计数器。
• 同步滚动：两个窗格中的匹配键对齐。
• 交互式行高亮：将鼠标悬停在任一窗格中的任何字段上，以高亮显示另一个窗格中的相应键。
• 幻觉检测：高亮显示朴素自回归输出中遗漏或幻觉的键。

命令行基准测试运行器

针对预配置的企业预设运行基准测试套件：

python3 -m core.benchmark

输出示例：

======================================================================
并行约束 vs. 自回归生成基准测试
======================================================================
--> 正在运行预设：金融科技欺诈检测（4 个字段）...
    自回归基线：          421.3 ms | 148 个 token (122.4 tok/s) | 传递次数：148
    并行约束：             74.8 ms |   0 个 token (O(1))           | 传递次数：1
    >> 加速：5.6 倍更快 (步数减少：148.0 倍)
    >> 模式匹配：朴素=True | 并行=True (100% 保证)
----------------------------------------------------------------------
--> 正在运行预设：支持分流矩阵（28 个字段）...
    自回归基线：         1894.2 ms | 312 个 token (131.2 tok/s) | 传递次数：312
    并行约束：            268.4 ms |   0 个 token (O(1))           | 传递次数：1
    >> 加速：7.1 倍更快 (步数减少：312.0 倍)
    >> 模式匹配：朴素=True | 并行=True (100% 保证)
----------------------------------------------------------------------
--> 正在运行预设：高基数关税（1 个字段，255 种选择）...
    自回归基线：          498.7 ms |  42 个 token (116.5 tok/s) | 传递次数：42
    并行约束：             88.6 ms |   0 个 token (O(1))           | 传递次数：1
    >> 加速：5.6 倍更快 (步数减少：42.0 倍)
    >> 模式匹配：朴素=True | 并行=True (100% 保证)
----------------------------------------------------------------------

仓库结构

.
├── core/
│   ├── __init__.py           # SDK 包导出
│   ├── engine.py             # 并行约束解码和自回归引擎
│   ├── schema.py             # 模式定义、元数据编译器和 Logit 映射
│   ├── prompt_builder.py     # 用于预填充目录和朴素基线的提示模板
│   └── benchmark.py          # 命令行基准测试运行器
├── presets/
│   ├── fintech_fraud.json    # 欺诈检测场景（4 个字段）
│   ├── code_security.json    # 漏洞审计场景（4 个字段）
│   ├── support_triage.json   # 企业工单分流（28 个字段）
│   └── high_cardinality_255.json # 255 种选择的关税分类器
├── server/
│   ├── app.py                # FastAPI 端点（/api/run-parallel, /api/stream-naive）
│   └── main.py               # 服务器启动器
├── web/
│   ├── index.html            # 并排比较界面
│   ├── app.js                # 前端流式处理与同步滚动
│   └── style.css             # 界面样式
├── MODEL_CARD.md             # Hugging Face 模型卡片文档
├── requirements.txt          # Python 包需求
├── run.sh                    # 启动脚本
└── README.md                 # 项目文档

支持的模型

该引擎目前配置为使用 mlx-community/Qwen2.5-1.5B-Instruct-4bit。

任何受 mlx-lm 支持的解码器 LLM 都可以通过设置 core/engine.py 中的 MODEL_ID 来加载。

许可证

Apache 2.0