用统一 Ruby API 接入多家 AI 提供商，在 Ruby/Rails 中构建聊天、工具、多模态与 Agent 应用

方案简介

RubyLLM 是 Ruby 原生 AI 框架，让开发者用一套一致的 Ruby API 使用聊天、工具调用、Agent、图像、音频和视频等 AI 能力，支持纯 Ruby 脚本或 Rails 应用。它内置十七家提供商支持（OpenAI、xAI、Anthropic、Google、AWS、Ollama 等），还可直接连接任意 OpenAI 兼容端点，从而避免为每家厂商学习不同的 SDK。该方案适合希望在 Ruby/Rails 项目中快速加入 AI 功能的团队：两分钟内即可跑通一个 AI 聊天，且在 Rails 中 API 直接作用于你自己的 Chat 和 Message 记录，配合 Active Storage 附件、Hotwire 流式推送与后台任务。项目在 chatwithwork.com 经受实战检验，GitHub 获 4342 星。

亮点与能力

• Chat： 通过 RubyLLM.chat 进行对话式 AI 交互
• Vision： 分析图像和视频
• Audio： RubyLLM.transcribe 转录语音，RubyLLM.speak 生成语音
• Documents： 就 PDF、文本文件等格式提问
• OCR： 用 RubyLLM.ocr 将文档转为 markdown
• 图像/视频生成： RubyLLM.paint 与 RubyLLM.animate
• Embeddings 与 Reranking： 生成向量并按相关性排序检索候选
• Tools 与 Agent： 让 AI 调用 Ruby 方法，用 RubyLLM::Agent 定义可复用助手
• Streaming： 用块实现实时流式响应
• 结构化输出： 定义 Ruby schema，用 response.parsed 读取结果
• 成本追踪： chat.tokens 与 chat.cost 提供每次尝试的用量账本

组成与分工

• RubyLLM：核心框架，提供统一的 chat/paint/embed/transcribe 等 Ruby 方法及模型注册表
• OpenAI / Anthropic / Gemini / Ollama 等 17 家提供商：实际执行推理、图像生成、嵌入等任务的底层模型服务
• Rails：应用框架，RubyLLM 的 API 直接作用于 Rails 的 Chat/Message 记录
• Active Storage：管理会话中的文件附件
• Hotwire：流式推送响应到前端
• Faraday：示例中工具方法内发起 HTTP 请求
• Schematist::Schema：定义结构化输出的 Ruby schema

前置要求

• Ruby 环境（纯 Ruby 脚本或 Rails 应用均可）
• 至少一家 AI 提供商的 API 密钥（OpenAI、Anthropic、Gemini、Ollama 等）
• 安装 2.0 发布候选版本：

实施步骤

1. 安装 gem

bash
bundle add ruby_llm --version 2.0.0.rc1

2. 配置提供商

在脚本中或 Rails 的 config/initializers/ruby_llm.rb 里配置要使用的提供商：

ruby
require 'ruby_llm'

RubyLLM.configure do |config|

3. 发起第一次对话

ruby
chat = RubyLLM.chat
chat.ask "What's the best way to learn Ruby?"

4. 按需扩展能力

可给对话添加文件、工具、schema 等，例如多模态提问：

ruby
chat = RubyLLM.chat(model: "gemini-3.7-flash")
chat.ask "What's in this image?", with: "ruby_conf.jpg"

或定义 Agent：

ruby
class WeatherAssistant < RubyLLM::Agent
model "gpt-5.6-luna"
instructions "Be concise and always use tools for weather."
tools Weather
end

WeatherAssistant.new.ask "What's the weather in Berlin?"

使用与配置要点

日常使用要点：

• 流式响应： 用块逐块读取：

ruby
chat.ask "Tell me a story about Ruby" do |chunk|
print chunk.content
end

• 结构化输出： 定义 schema 后用 response.parsed 读取解析结果：

ruby
response = chat.with_schema(ProductSchema).ask "Analyze this product", with: "product.txt"
response.parsed

• 生成媒体： RubyLLM.paint 生成图片、RubyLLM.animate 生成视频，返回对象可直接 save 到本地文件。
• 验证成功： 调用 chat.ask 后能读回响应文本、生成文件和用量信息即说明配置正确："Read response text, generated files, and usage through Ruby objects."

注意事项与常见问题

• README 示例针对 2.0.0.rc1 版本，安装时需指定该候选版本号。
• 分析图像等多模态输入时需选择支持对应输入类型的模型（示例中用 model: "gemini-3.7-flash"）。
• 仓库描述提示 "A handful of small dependencies keeps it easy to bring into an existing application"，依赖较轻但完整安装配置细节需参考官方 Getting Started 文档。
• README 中配置代码被截断，完整初始化配置需查阅 GitHub 仓库原文。

优缺点

• ✓ 一套代码切换 17 家提供商
• ✓ 聊天、媒体、嵌入、Agent 全覆盖
• ✕ 需自行配置各家 API 密钥
• ✕ 依赖各提供商模型能力差异

出处

本方案挖掘自开源项目 crmne/ruby_llm，方案内容与实施命令均来自其 README 原文。