Communitygithub.com

nynuz/ml-serving-skills

用於服務機器學習模型的代理技能集合,從 API 後端到前端。

ml-serving-skills 是什麼?

此技能從 Hugging Face model_id 生成一個完整、可在本地執行的生產級 FastAPI 專案。它支援四種任務系列:文字分類、標記分類(NER)、文字嵌入和影像生成,並自動根據模型元資料判斷應使用的端點形狀與底層函式庫(transformers、sentence-transformers、diffusers)。專案涵蓋模型初始化僅一次、批次處理、輸入/輸出驗證、健康檢查、結構化錯誤處理與可選的評估/基準測試腳本。適用於 Claude Code、Coder 及 Cursor 等平台,但明確限定於本地單一使用者場景,不包含認證、速率限制或雲端部署。開發者應先確認 model_id,執行內建檢查腳本,再對照對應的參考文件審查產出,最後透過 uvicorn 在本機啟動服務。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add nynuz/ml-serving-skills

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HF Model → FastAPI Builder

這個技能的作用

接受一個 Hugging Face model_id,並圍繞它產生一個自包含、可在本地執行的生產級 FastAPI 專案:分層的應用程式結構、模型僅在啟動時載入一次(絕不每次請求都載入)、適合任務的推理端點、具有明確上限的批次處理、輸入/輸出驗證、健康與就緒探測、結構化錯誤處理,以及可選的評估/基準測試腳本。

它支援四種任務系列,每種具有不同的端點形狀和底層函式庫:

任務系列HF 概念函式庫參考檔案
文字分類AutoModelForSequenceClassificationtransformersreferences/text-classification.md
標記分類 (NER)AutoModelForTokenClassificationtransformersreferences/token-classification-ner.md
文字嵌入句子嵌入模型sentence-transformersreferences/embeddings.md
影像生成擴散管道diffusersreferences/image-generation.md

範圍邊界 — 開始前請先閱讀

  • 僅限本地。 不包含 Docker、Kubernetes 或雲端部署(Railway、AWS 等)。輸出是使用者可透過 uvicorn 在自己機器上執行的專案。
  • 僅限後端。 絕不產生前端/客戶端程式碼(React、Next.js、fetch 呼叫等)。如果使用者想要一個 UI 來呼叫 API,告訴他們那是另一個關注點,並在 API 邊界處停止。允許寬鬆的本地 CORS 以便前端開發伺服器稍後可以呼叫 API 是沒問題的——那是後端配置的關注點,不是前端程式碼。
  • 服務,不是訓練。 如果使用者想要微調或訓練模型,這個技能是錯誤的工具——請直接說明。
  • 本地、單一使用者威脅模型。 產生的服務預設沒有認證和沒有速率限制——它們設計在 localhost 上執行。它們確實會強制執行輸入成本上限(批次大小、每個字串長度、生成參數,以及請求本體大小限制 → 413)。始終告知使用者不要將服務綁定到 0.0.0.0 或將其暴露到 localhost 之外,除非先添加認證、速率限制和強化 CORS 政策——這些超出此技能範圍。
  • 未經詢問,不要安裝或啟動任何東西。 建立專案架構,並給使用者確切的命令來執行。只有在使用者明確要求您驗證其是否正常運作時,才自行執行 pip install 或啟動 uvicorn——其中一些依賴項(torch、diffusers)的下載量很大。

工作流程

步驟 1:收集輸入

您需要:

  • model_id(必要)— Hugging Face Hub ID,例如 distilbert-base-uncased-finetuned-sst-2-english。
  • 輸出目錄(如果未給定則詢問,否則預設為目前工作目錄下的 ./<model-name-slug>-api)。
  • 可選:一個小型標記評估資料集路徑(用於後續的正確性評估)、一個連接埠(預設 8000)。

如果使用者只描述了他們在筆記本中做了什麼(「我用 pipeline(...) 載入它,它分類情緒」),如果沒有說明確切的 model_id,請詢問——下游的一切都依賴於它。

步驟 2:檢查模型

執行內建的檢查程式——它只會命中公開的 HF Hub API,絕不下載模型權重:

python scripts/inspect_model.py <model_id>

它會輸出 JSON,包含 task_family、pipeline_tag、library_name、architectures、id2label(如果有)、num_labels、近似參數計數和裝置推薦事項。

  • 如果 task_family 返回的是四個支援的系列之一,則繼續。
  • 如果它返回 "unknown" 或者您不同意其猜測(有些儲存庫缺少/錯誤的元資料),請詢問使用者四個任務系列中哪一個適用——不要默默地猜錯,整個端點形狀都取決於它。
  • 如果腳本報告 not_found_or_gated,HF 的公開 API 返回 401/403/404——這表示 model_id 要嘛錯誤/拼錯,要嘛儲存庫是閘控/私有的。它無法告訴您是哪一種。首先與使用者再次確認確切的 model_id(拼寫錯誤和錯誤的組織命名空間是最常見的原因);僅在確認正確後,才應將其視為閘控,並要求使用者在模型頁面上接受授權並進行身份驗證。建議透過 HF_TOKEN 環境變數傳遞令牌(HF_TOKEN=hf_xxx python scripts/inspect_model.py <model_id>)或 huggingface-cli login——避免使用 --token 旗標,因為命令列上的令牌會洩漏到 shell 歷史記錄和行程清單中。

步驟 3:讀取匹配的參考檔案

在建立架構之前,請讀取步驟 2 中任務系列對應的 references/<task-family>.md。它包含確切的管道/模型載入程式碼、請求/回應架構以及特定任務的注意事項(例如分類的標籤映射、NER 的實體聚合、嵌入的池化策略、生成的影像編碼)。同時,每個工作階段略讀一次 references/architecture.md——它涵蓋了所有四個任務系列相同的部分(生命週期載入、健康探測、CORS、錯誤處理),這樣您就不必每次都重新推導它們。

對於參考檔案未涵蓋的任何關於模型載入、分詞、裝置放置(CPU/CUDA/MPS)或 dtype 選擇的問題,請使用已安裝的 transformers-huggingface 技能——它擁有 transformers 函式庫本身的權威模式。

步驟 4:建立專案架構

使用從步驟 2 獲得的任務系列和任何標籤/配置資訊來執行生成器:

python scripts/scaffold_project.py \
  --model-id "<model_id>" \
  --task <text-classification|token-classification|embeddings|image-generation> \
  --output-dir "<output_dir>" \
  --id2label-json "<path-to-json-or-inline-json>"   # 可選,僅限分類/NER

執行 python scripts/scaffold_project.py --help 查看所有旗標(連接埠、最大批次大小、最大輸入長度/影像大小等)——傳遞您在步驟 2 中學到的任何相關資訊,而不是保留生成的預設值(如果您有更好的值)。

這會產生:

<output_dir>/
├── app/
│   ├── main.py            # FastAPI() + 生命週期(載入模型一次、預熱)、CORS、路由器掛載
│   ├── core/
│   │   ├── config.py      # pydantic-settings:來自環境變數的 MODEL_ID、DEVICE、MAX_BATCH_SIZE 等
│   │   └── model.py       # 為選定的任務系列載入模型 / 推理函式
│   ├── api/
│   │   └── routes.py      # 任務端點 + /health/live + /health/ready + /v1/info
│   └── schemas.py         # 帶有 Field 約束的 Pydantic 請求/回應模型
├── tests/
│   ├── test_health.py
│   └── test_inference.py  # 快樂路徑 + 一個驗證錯誤案例
├── requirements.txt       # 僅此任務系列需要的內容
├── .env.example
├── README.md              # 執行說明、端點文件、CORS 注意事項
└── .gitignore

架構生成器會填寫它可以程式化確定的內容(模型 ID、任務系列、如果傳遞了則包含標籤)。您仍然需要根據步驟 3 的參考檔案審查生成的 app/core/model.py 和 app/schemas.py——架構生成器不會呼叫模型,因此如果沒有傳遞 --id2label-json,它無法知道確切的標籤集,或者 NER 模型是否需要 aggregation_strategy="simple"。填寫它留下的任何 # TODO 標記。

步驟 5:驗證橫切生產關注事項

每個生成的專案都必須具備所有這些——明確檢查它們,它們很容易在手動編輯生成的程式碼時被無聲地遺漏:

  • 模型在 lifespan 中載入,而不是在匯入時或每次請求時(app/main.py)
  • 載入後立即進行一次預熱呼叫(一次虛擬推理),這樣第一個真實請求就不會是慢的那個——請參閱 references/architecture.md
  • /health/live(程序存活,無依賴項檢查)是一個不同的函式,與 /health/ready(檢查模型是否已載入)不同——將它們混為一談會導致重啟連鎖,請參閱 references/architecture.md
  • 每個推理回應都包含模型 ID/版本——沒有商量餘地,這是日後偵錯「哪個模型產生了這個」的方法
  • 批次輸入具有伺服器強制的最大長度/大小(Field(..., max_length=...))——無限制的批次是無限制的 GPU/CPU 花費。架構生成器還會限制每個單獨的字串(StringConstraints(max_length=...),使用 --max-chars-per-text 調整),並透過 main.py 中的 413 中介軟體拒絕過大的請求本體(--max-request-mb)——請驗證兩者在任何手動編輯後仍然存在,因為本體大小檢查是唯一一個在有效負載被解析到記憶體之前觸發的防護措施
  • CPU/GPU 綁定的推理透過 anyio.to_thread.run_sync(...) 執行,絕不直接在 async def 處理程式中執行——否則它會阻塞每個進行中請求的事件迴圈
  • 驗證錯誤返回 422 並附帶有用的訊息;模型/執行時期錯誤被捕獲並映射到類型化的 HTTP 錯誤,絕不會有未處理的 500 錯誤將堆疊追蹤洩漏給客戶端

請參閱 references/batching.md 了解預設使用的批次陣列模式,以及何時(在本地單一使用者設定的罕見情況下)動態微型批次處理值得增加複雜性。

步驟 6:測試

架構生成器使用 fastapi.testclient.TestClient 生成 tests/test_health.py 和 tests/test_inference.py(請參閱 references/testing-and-evaluation.md)。閱讀它們,調整範例輸入/預期形狀以匹配實際模型,並告訴使用者執行:

pytest

步驟 7:評估和基準測試(可選,僅在使用者想要時)

提供了兩個獨立的腳本——將它們複製到生成的專案目錄中(它們不是 FastAPI 應用程式本身的一部分,它們是呼叫正在執行的伺服器的工具):

  • scripts/evaluate.py — 正確性:對執行中的 API 執行標記資料集(CSV/JSONL)並報告準確率/F1(分類、NER)或餘弦相似度合理性檢查(嵌入)。需要使用者的標記資料——詢問路徑,或者如果他們還沒有,則跳過此步驟。
  • scripts/benchmark.py — 效能:對執行中的 API 發出並發請求,並報告 p50/p95/p99 延遲和吞吐量。不需要標記資料,只需要幾個範例輸入。

請參閱 references/testing-and-evaluation.md 了解確切用法以及如何解釋輸出。

步驟 8:總結

給使用者確切的命令以在本地執行:

cd <output_dir>
python -m venv .venv && source .venv/bin/activate   # 或 Windows 上使用 .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

引導他們前往 /docs 進行互動式測試(FastAPI 自動生成的 OpenAPI UI)。明確說明您沒有做什麼:沒有 Docker 映像、沒有雲端部署、沒有前端程式碼。如果他們接下來想要其中任何一個,那都超出了此技能的範圍。

故障排除

  • inspect_model.py 返回 task_family: unknown:儲存庫的元資料不完整。直接詢問使用者它屬於四個系列中的哪一個,並將 --task 明確傳遞給架構生成器。
  • 模型需要 trust_remote_code=True / 自訂程式碼:在建立架構之前向使用者標記此問題——這意味著來自 Hub 的任意程式碼將在本地執行;在生成設定該旗標的專案之前,請獲得明確的確認。
  • 使用者想要表格中沒有的任務系列(例如語音、翻譯、VQA):清楚地說明此技能目前僅涵蓋列出的四個系列,並提議使用 references/architecture.md 中的相同架構模式手動建立 FastAPI 包裝器,而不是強行將其塞入四個參考檔案之一。
  • 生成的 requirements.txt 安裝速度慢/體積大:torch 和 diffusers 很大;如果任務系列會拉入它們,請在使用者執行 pip install 之前警告他們。

相關技能