Show HN：Spinf-serve — 用於批次評分與決策的推理伺服器

一次 GPU 的批次分類與決策推斷。

spinf-serve 只讀取一次內容，並在同一次傳遞中回答多個問題。每個答案都是對你給定選項的機率，而非產生的文字。它在一臺 24 GB NVIDIA GPU 上執行，並提供與 spinf 主機服務相同的 OpenAI 相容 API。Apache 2.0。

為什麼存在

我們為自己的工作構建了這個引擎：從數百萬篇新聞文章中每日讀取市場指數，每篇文章都提出數十個精準、校準的問題。為聊天設計的服務引擎會為每個問題重新閱讀內容，並一次產生一個 token，這使得工作既慢又昂貴。spinf-serve 將每個問題作為一次閱讀內容的分支，並將多個內容打包進一次前向傳遞。批次分類是它的起點，也是其最強項。

同樣的機制現在稱為 decision model：一種返回對固定答案集合（是或否、標籤、等級）的機率，而非段落的模型。任何開放式指令模型在 spinf-serve 中都以此方式運作，專用的決策模型則保持原樣。託管的 spinf API 由此引擎衍生；我們發布它是因為有人要求在自己的硬體上執行。

它不是聊天伺服器。除非你要求，否則不會產生任何文字，且它是為吞吐量而非單一請求延遲設計。

安裝與執行

Linux、具備 24 GB 及 fp8 tensor core 的 NVIDIA GPU（Ada、Hopper 或 Blackwell：RTX 4090 / 5090、L4、L40S、RTX 6000 Ada、H100）、支援 CUDA 13 的驅動程式、Python 3.12。Ampere 卡使用 int8 權重 (configuration)。

pip install "spinf-serve[server]"
spinf-serve serve spinf/gemma-4-12b-fp8          # downloads the checkpoint on first start; serves on port 8000

或使用已安裝 NVIDIA Container Toolkit 的映像檔（卷會保留模型和編譯快取；映像名稱後的引數即為 spinf-serve serve 的引數）：

docker run --gpus all -p 8000:8000 -v spinf-cache:/root/.cache ghcr.io/spinfinc/spinf-serve

然後詢問。從一次閱讀內容中進行兩次分類和一次抽取：

curl http://localhost:8000/v1/score \
  -H "Content-Type: application/json" \
  -d '{
    "model": "spinf/gemma-4-12b-fp8",
    "messages": [
      { "role": "user",
        "content": "Customer support message:\nI was charged twice for September, please refund one of the charges." }
    ],
    "scoring": {
      "queries": [
        { "id": "topic",
          "template": "\n\nTopic (billing, technical, account, shipping, or cancellation):{?}",
          "options": [" billing", " technical", " account", " shipping", " cancellation"] },
        { "id": "refund",
          "template": "\n\nIs the customer asking for a refund?\nAnswer:{?}",
          "options": [" yes", " no"] },
        { "id": "month",
          "template": "\n\nQ: Which month was charged twice?\nA: \"{*}\"" }
      ]
    }
  }'

對於每個已評分的問題，回覆會給出每個選項的機率，並在空內容時給出相同機率（12B 模型的實數）：

{ "id": "refund", "combinations": [ { "values": {}, "options": [
    { "text": " yes", "logprob": -0.90, "p": 0.72, "floor_p": 0.60 },
    { "text": " no",  "logprob": -1.86, "p": 0.28, "floor_p": 0.40 } ],
    "residual": 0.44 } ] }

p 是你選項中的機率。floor_p 是沒有內容時的相同問題，因此 p - floor_p 是內容所增加的部分（此處 topic 將 " billing" 從 0.47 提升至 0.91）。residual 是落入你選項之外的詞的機率。對於 month，回覆列出最可能的答案及其機率（"September" 首位）。相同的內容，配合 API 金鑰，對 api.spinf.com 進行運算；OpenAI SDK 透過 /v1/chat/completions 在 scoring 區塊中使用 extra_body（quickstart）。

你得到的

• 一次閱讀，多個問題。內容只讀取一次；每個問題都是同一次傳遞的分支，僅消耗其自身的 token。佔位符將單一模板轉換為問題網格。
• 可設定閾值的分數。每個選項都有機率、下限與對數機率；決策則是你在自身資料上設定的閾值（calibration）。
• 抽取自同一次閱讀：{*} 文字、{n} 數字與 {$} 金額，並以機率解碼，或將自由文字產生至槽位。
• 無論批次中其他內容為何，分數皆相同。使用 fp8 checkpoint 時，單一內容的分數在獨立或與數千個其他內容打包時、跨呼叫、跨日、跨伺服器皆為位元相同。system_fingerprint 表示兩個回覆不可比。
• 影像、音訊與影片畫面位於內容中，適用於能閱讀它們的模型。
• Prompt packs. 即時使用、已校準的問題集，適用於各種工作（內容審核、分診、產品列表、評論、品牌、娛樂），已預載並在請求中命名（以下）。
• Hosted or self-hosted. 使用者可以通過更改基本 URL 和金鑰，在此伺服器與 api.spinf.com 之間切換。spinf-client 與兩者通訊；agent skills 教導程式碼代理程式使用 API、此伺服器以及 pack 格式。

速度

在一臺 RTX 4090 上使用 Gemma 4 12B（fp8）測試：24 篇 Wikinews 文章約 470 tokens，56 題每篇，每題兩選項，共 1,344 題（公共工作集在 fixtures/），通過 HTTP 傳送給 spinf-serve 及 vLLM 0.26，使用字首快取。指令碼與完整結果在 benchmarks/。

vLLM 已經透過字首快取，在其 56 題中重複使用每篇文章。它無法一次前向傳播完成所有答案：它執行 1,344 個單 token 請求，而 spinf-serve 則將 56 題作為一個讀取的分支，並將 24 篇文章打包成兩個 16k token 的傳遞。隨著每篇內容的題數增加，差距也會擴大。

實際上，在 4090 與 12B 模型下：spinf/moderation pack（每訊息 106 題，22 個類別）每小時可處理約 20,000 條訊息；一篇新聞文章提出 74 題，讀取速率接近 700 題/秒。提取槽位會增加解碼工作（搜尋槽約相當於 200~600 token 的評分，生成槽最多約 2,000 token），但共用讀取。

Prompt packs

一個工作通常不只一題：內容審核有 106 題，每題已對正常流量校準，並合併成類別分數與決策。prompt pack 是一個檔案，包含題目、內容呈現方式、答案轉成分數、分數轉成決策的流程。伺服器預載 pack，請求中命名一個（"packs": [{"id": "spinf/moderation"}]），從同一次讀取中取得該 pack 的類別與決策，接著處理自己的題目。

官方 pack 位於 spinf-prompts，預設已載入。伺服器可從任何 GitHub 倉庫或本地資料夾載入 pack，透過 --packs 指定；PACKS.md 列出我們已知的所有 pack，包括我們的與其他人的，並且可透過 issue 新增。格式、請求欄位與來源：docs/prompt-packs.md。

Models

每個都是我們量化並校準的 checkpoint，已發布於 Hugging Face Hub，附帶其配方（quantizations/）；引擎鎖定其已進行等效測試的修訂版。任何其他 Hub checkpoint（受支援的架構族）皆可透過其路徑執行，載入時進行量化。

Documentation

docs/: quickstart, examples, scoring API, configuration, writing questions, calibration, prompt packs, FAQ; the guides (decision models, probabilities you can act on, few-shot classification, sentiment, survey coding, moderation, intent routing); and the 關於引擎運作的工程檔案 (architecture, batch invariance, precision, the Qwen stack, extraction).

狀態

版本 0.1。引擎（scoring、extraction、generation、media、batch invariance、兩個模型堆疊）已完成並已進行等效測試；伺服器提供主機服務的公開 API；四個檢查點為公開。尚未完成的專案列於 docs/README.md。

問題、想法與錯誤請提交至此倉庫的 issues。 沒有論壇或聊天，任何事都不算小。

佈局

spinf_serve/ 持有引擎 (protocol, compiler, packer, scorer, extract, service)，提供模型的 manifest，packs 模組（純 Python，亦供客戶端與託管 API 使用），每個架構族別在 models/ 擁有一個模型堆疊，量化方案位於 quant/，HTTP 伺服器位於 server/，以及 spinf-serve 指令。quantizations/ 每個已釋出的 checkpoint（配方、校準輸出、模型卡）都有一個資料夾，fixtures/ 公開的 parity fixture 及參考，benchmarks/ 吞吐量比較。程式碼地圖為 docs/ARCHITECTURE.md。

開發

uv sync --extra server
uv run pytest                                   # CPU tests (the official packs' golden fixtures need ../spinf-prompts or SPINF_PROMPTS_DIR)
uv run ruff check . && uv run ruff format --check .
CUDA_VISIBLE_DEVICES=0 uv run spinf-serve parity --fixture fixtures/wikinews_20261024.json.gz \
    --reference fixtures/wikinews_20261024.spinf-gemma-4-12b-fp8.json.gz --passes 2

每一次觸及核心、編譯邊界或量化方案的變更，皆會隨 GPU parity 進行執行： 在每個已釋出的 checkpoint 的記錄參考上，提供完全相同的 log‑probabilities（fixtures/）。 相依性被精確固定；它們僅隨 parity 進行變更。詳見 CONTRIBUTING.md。

授權與致謝

Apache 2.0 (LICENSE, NOTICE)。我們執行並重新量化的模型、我們構建的專案、我們實作的技術，以及我們驗證的資料，皆在 ACKNOWLEDGEMENTS.md 中獲得致謝。