Yinsongxu/LLM2Jev

Turn local language models into Jev-style structured decision models. Get results from text and images with prefill alone—no token-by-token decoding required.

🧠 什么是 LLM2Jev？

LLM2Jev 是一个开源库，可让您将本地大型语言模型 (LLM) 作为 Jev 风格的决策引擎 运行。它不是逐 token 生成文本，而是预填充模型一次，读取 logits，并直接计算一组答案候选的概率。结果是结构化的决策输出（例如分数、选择），可供期望 Jev / System One API 的应用程序使用。

该项目支持三个后端：

SGLang – 高性能推理服务器，可缓存前缀（Radix Cache）并高效评分多个候选。
Transformers – 经典的 Hugging Face 管道。
MLX – 适用于文本和视觉模型的 Apple-Silicon 原生推理。

它支持纯文本以及多模态输入（文本 + 图像），并可通过 Python API 或与 Jev 的 /v1/systemone API 兼容的 HTTP 端点访问。

✨ 核心功能（根据 README 描述）

功能	说明
广泛的后端支持	通过 SGLang、Transformers 或 Apple Silicon 上的 MLX 运行本地 LLM（仅文本或视觉语言）。
仅 prefill 推理	模型运行一次以产生 logits；候选概率从这些 logits 推导，无需迭代解码。
Apple Silicon 加速	MLX 后端在 M 系列 Mac 上提供量化模型、批处理和前缀重用。
多模态输入	您可以在请求的 `state` 或 `instructions` 中提供图像和文本。
顺序无关评分	每个候选独立评估，因此打乱选项不会影响分数。
冷请求上的前缀重用	对于具有多个候选的长提示，第一个候选建立缓存，后续候选重用该缓存，减少冗余工作。
与 Jev 兼容的 HTTP 服务	公开模拟官方 Jev API 的 `POST /v1/systemone` 端点。

🚀 快速开始（Linux + NVIDIA GPU 示例）

# 克隆并安装 SGLang 后端的额外依赖项
git clone https://github.com/Yinsongxu/LLM2Jev.git
cd LLM2Jev
uv sync --extra sglang   # 或 `pip install -e .[sglang]`
source .venv/bin/activate

# 使用本地因果模型（HF 格式）运行演示脚本
python examples/sglang_inference.py --model-path /path/to/model

此脚本向模型发送 Choice、Score 和 Noul 问题，并打印 JSON 响应。

对于 Apple-Silicon 用户，相同的命令可与 MLX 后端配合使用（请参阅安装文档）。基于图像的请求涵盖在 docs/multimodal.md 中。

📦 安装

存储库提供详细指南（docs/installation.md），列出：

Python 3.12+ 要求
可选额外项：sglang、transformers、mlx
CUDA（Linux）或 Metal（macOS）的系统库
推荐的包管理器 uv（备用为 pip）

📖 开始使用

使用指南（docs/usage.md）引导您了解：

离线 Python API – 用于评分的直接函数调用。
在线 HTTP 服务 – 启动接受 Jev 兼容请求的服务器。
在 staged（前缀重用）和 all（无重用）评分策略之间选择。
如何构建多模态负载。

🎮 演示

演示	说明
Web 演示	交互式 UI，用于提交问题并查看概率分解。（`demos/web/README.md`）
贪吃蛇演示	一个小型游戏，LLM 根据当前棋盘状态决定蛇的移动。（`demos/snake.py`）
MuJoCo 拾取与放置	展示机器人手臂使用 LLM 驱动的决策拾取物体。（`demos/pick_place/README.md`）

README 中包含动画 GIF 以说明每个演示。

📊 基准测试

Qwen3-1.7B 模型在 RTX 5090 上的性能数据记录在 docs/shared-prefix-benchmarks.md 中。基准测试比较：

staged（前缀重用）与 all（无重用）
冷缓存与热缓存场景
输入长度和候选数量对延迟和吞吐量的影响。

🗺️ 路线图（当前状态）

✅ 交互式 Web 演示已完成
✅ Transformers 和 SGLang 的初始本地图像支持
⬜ 扩展更多模型大小和数据集的基准测试
⬜ 添加更多多模态任务和演示
⬜ 更深入评估决策质量与延迟的权衡

🧪 测试

使用以下命令运行测试套件：

python -m unittest discover -s tests -v

存储库包含评分管道和 HTTP 服务的单元测试。

📄 许可证

Apache License 2.0 – 免费用于商业和学术用途。

TL;DR：LLM2Jev 通过直接对单次 prefill 传递中的候选答案进行评分，将任何本地运行的 LLM（文本或视觉）转变为快速、与 Jev 兼容的决策引擎。它支持 SGLang、Transformers 和 Apple-Silicon MLX 后端，提供 Python API 和 HTTP 服务，并包含从 Web UI 到机器人手臂模拟等演示。