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 到機器手臂模擬等示範。