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。
团队 – 需要开箱即用的成本可见性和结构化输出验证的团队。
运维 / 可观测性人员 – 需要现成的 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。它抽象掉了每个提供商的特性，让你专注于提示词和所需的数据。