agentjido/req_llm

什麼是 ReqLLM？

ReqLLM 是一個開源的 Elixir 函式庫，讓你能夠透過單一且一致的 API 與許多大型語言模型 (LLM) 提供商（OpenAI、Anthropic、Azure、Google Gemini 等）進行對話。它基於流行的 Req HTTP 用戶端與 Finch 串流傳輸函式庫構建，處理每個提供商的特性，因此無論你使用哪個模型，都可以編寫相同的 Elixir 程式碼。

為什麼它很重要

提供商無關 – 函式庫的模型目錄中註冊了來自 21 個以上提供商的 1,200 多個模型。你只需使用類似 "anthropic:claude-haiku-4-5" 的字串選擇模型，函式庫就會將請求轉換為該提供商正確的 HTTP 格式。
統一的高階助手 – generate_text/3、stream_text/3、generate_object/4 等函式模仿了 Vercel AI SDK 的風格，因此你可以使用相同的呼叫簽章生成純文字、結構化 JSON 甚至圖像。
串流傳輸支援 – 透過 Finch 在提供商之間實現即時 Token 串流傳輸，為你提供一個在收集使用情況元數據的同時產出 Token 的 StreamResponse。
結構化輸出與工具呼叫 – 你可以描述期望結果的形狀（物件、陣列、JSON Schema 等），函式庫將驗證提供商的響應，使函式呼叫工作流變得更加容易。
成本與使用情況追蹤 – 每次響應都包含 Token 計數與盡力而為的 USD 成本估計，此外還有可以接入 OpenTelemetry 或其他可觀測性堆疊的 Telemetry 事件。

核心概念（快速速查表）

概念	說明	典型用途
Model spec	一個識別提供商與模型 ID 的字串、元組或 `%LLMDB.Model{}`（例如 `"openai:gpt-4o"`）。	選擇要呼叫的模型。
Context	使用 `ReqLLM.Context.*` 構建的系統/使用者/助手訊息列表。	提供多輪對話歷史。
Output descriptor	宣告期望形狀（文字、物件、陣列、JSON Schema 等）的 `ReqLLM.Output` 結構體。	要求模型回傳結構化數據。
Response structs	`ReqLLM.Response`、`ReqLLM.StreamResponse`、`ReqLLM.Usage`。	檢查生成的文字、圖像、嵌入、使用情況與成本。
Provider transports	內部由 Req 構建 HTTP 請求；Finch 處理串流傳輸。	你永遠不需要直接呼叫 Req 或 Finch。
Key management	`ReqLLM.Keys` 從環境變數、`.env` 檔案或記憶體儲存中提取 API 金鑰。	將憑證與程式碼分離。

開始使用（最短路徑）

# 透過 Igniter 新增函式庫（推薦）
mix igniter.install req_llm

# 在你的程式碼中
model = "anthropic:claude-haiku-4-5"

# 簡單的單次文本生成
text = ReqLLM.generate_text!(model, "Hello world")
# => "Hello! How can I assist you today?"

# 結構化物件生成
schema = [name: [type: :string, required: true], age: [type: :pos_integer]]
person = ReqLLM.generate_object!(model, "Generate a person", schema)
# => %{name: "John Doe", age: 30}

串流傳輸：

{:ok, resp} = ReqLLM.stream_text(model, "Write a short story")
ReqLLM.StreamResponse.tokens(resp) |> Stream.each(&IO.write/1) |> Stream.run()

值得深入研究的顯著功能

提供商特定選項 – 例如，provider_options: [web_search: %{max_uses: 5}] 可啟用 Anthropic 的網路搜尋工具。
嵌入生成 – 如果提供商支援，Embedding.generate/3 會回傳單個或批次嵌入。
OpenAI 即時會話 – 用於較新的即時模型的底層 WebSocket API (ReqLLM.OpenAI.Realtime)。
Telemetry – 內建的 Telemetry 事件 ([:req_llm, :request, …], [:req_llm, :token_usage]) 以及選擇性的 OpenTelemetry 掛載，用於完整的追蹤。
可擴展的模型註冊表 – 你可以透過傳遞完整的 spec map並使用 ReqLLM.model!/1 進行規範化，來呼叫尚未在目錄中列出的模型。

誰應該使用它？

Elixir 開發者 – 構建聊天機器人、代理人或任何由 GenAI 驅動的服務，並且希望使用單一且慣用的用戶端而不是處理數十個提供商的 SDK。
團隊 –需要開箱即用的成本可視性與結構化輸出驗證的團隊。
Ops / 可觀測性人員 –需要現成的 Telemetry 鉤子用於計費儀表板的人員。

了解更多

Hex 套件頁面 – https://hex.pm/packages/req_llm
完整文件 – https://hexdocs.pm/req_llm/
提供商指南 –參閱儲存庫中的 guides/（例如 guides/openai.md）。
Discord 社群 –https://jido.run/discord (The Swarm: Elixir AI Collective)。

TL;DR

ReqLLM 為你提供了一個單一的 Elixir API 來呼叫數百個 LLM 模型（文字、嵌入、圖像、語音、OCR 等），並內建了串流傳輸、結構化輸出、成本追蹤與 Telemetry。它抽象掉了每個提供商的特性，讓你專注於提示詞與所需的數據。