[!NOTE] 您在使用 RubyLLM 吗？分享您的故事吧！只需 5 分钟。

---

构建聊天机器人、AI 助手和 RAG 应用程序。支持 OpenAI、xAI、Anthropic、Google、AWS、本地模型以及任何兼容 OpenAI 的 API。

两分钟内从零打造一个 AI 聊天应用

https://github.com/user-attachments/assets/65422091-9338-47da-a303-92b918bd1345

为什么选择 RubyLLM？

每个 AI 提供商都提供各自臃肿的客户端，API 不同、响应格式不同、规范也各异，让人应接不暇。

而 RubyLLM 则为您提供一套统一且简洁的 API，无论您使用的是 GPT、Claude 还是本地的 Ollama，接口都保持一致。仅需三个依赖：Faraday、Zeitwerk 和 Marcel，简单明了。

让我们看看代码吧

# 直接提问
chat = RubyLLM.chat
chat.ask "学习 Ruby 的最佳方法是什么？"

# 分析任意文件类型
chat.ask "这张图片里有什么？", with: "ruby_conf.jpg"
chat.ask "这段视频讲了什么？", with: "video.mp4"
chat.ask "请描述这次会议的内容。", with: "meeting.wav"
chat.ask "请总结这份合同。", with: "contract.pdf"
chat.ask "请解释这段代码。", with: "app.rb"

# 同时处理多个文件
chat.ask "分析这些文件。", with: ["diagram.png", "report.pdf", "notes.txt"]

# 流式响应
chat.ask "给我讲个关于 Ruby 的故事。" do |chunk|
  print chunk.content
end

# 生成图片
RubyLLM.paint "一幅水彩风格的山间日落图"

# 创建嵌入向量
RubyLLM.embed "Ruby 语言优雅而富有表现力。"

# 将音频转录为文本
RubyLLM.transcribe "meeting.wav"

# 内容安全审核
RubyLLM.moderate "请检查这段文字是否安全。"

# 让 AI 使用您的代码
class Weather < RubyLLM::Tool
  description "获取当前天气"
  param :latitude
  param :longitude

  def execute(latitude:, longitude:)
    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
    JSON.parse(Faraday.get(url).body)
  end
end

chat.with_tool(Weather).ask "柏林现在的天气如何？"

# 定义带有指令和工具的智能体
class WeatherAssistant < RubyLLM::Agent
  model "gpt-5-nano"
  instructions "言简意赅，始终使用工具查询天气。"
  tools Weather
end

WeatherAssistant.new.ask "柏林的天气怎么样？"

# 获取结构化输出
class ProductSchema < RubyLLM::Schema
  string :name
  number :price
  array :features do
    string
  end
end

response = chat.with_schema(ProductSchema).ask "请分析这款产品。", with: "product.txt"

核心功能

• 对话: 基于 RubyLLM.chat 的对话式 AI
• 视觉: 分析图像和视频
• 音频: 使用 RubyLLM.transcribe 转录并理解语音
• 文档: 从 PDF、CSV、JSON 等任意文件中提取信息
• 图像生成: 使用 RubyLLM.paint 创建图片
• 嵌入: 使用 RubyLLM.embed 生成嵌入向量
• 内容审核: 使用 RubyLLM.moderate 进行内容安全检测
• 工具: 让 AI 调用您的 Ruby 方法
• 智能体: 使用 RubyLLM::Agent 构建可复用的助手
• 结构化输出: 即开即用的 JSON 模式
• 流式传输: 支持块级实时响应
• Rails: 通过 acts_as_chat 集成 ActiveRecord
• 异步: 基于 Fiber 的并发机制
• 模型注册中心: 汇集 800 多种模型，具备能力检测与定价功能
• 扩展思考: 控制、查看及持久化模型推理过程
• 多提供商支持: OpenAI、xAI、Anthropic、Gemini、VertexAI、Bedrock、DeepSeek、Mistral、Ollama、OpenRouter、Perplexity、GPUStack，以及任何兼容 OpenAI 的 API

安装

将以下内容添加到您的 Gemfile：

gem 'ruby_llm'

然后运行 bundle install。

配置您的 API 密钥：

# config/initializers/ruby_llm.rb
RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
end

Rails 集成

# 安装 Rails 集成
bin/rails generate ruby_llm:install
bin/rails db:migrate
bin/rails ruby_llm:load_models # v1.13+

class Chat < ApplicationRecord
  acts_as_chat
end

chat = Chat.create!(model: "claude-sonnet-4")
chat.ask "这份报告里写了什么？", with: "report.pdf"

访问 http://localhost:3000/chats，即可获得开箱即用的聊天界面！

文档

rubyllm.com

贡献

详情请参阅 CONTRIBUTING.md。

许可证

采用 MIT 许可协议发布。

RubyLLM 快速上手指南

RubyLLM 是一个优雅的 Ruby API，统一封装了 GPT、Claude、Gemini 等主流大模型。它让你无需关心不同厂商的 API 差异，仅需极少的依赖即可构建聊天机器人、AI 代理和 RAG 应用。

环境准备

• 系统要求: 支持 macOS、Linux 及 Windows (WSL)。
• Ruby 版本: 建议 Ruby 3.1 或更高版本。
• 前置依赖: 无需额外安装系统级依赖，Gem 会自动处理核心依赖（Faraday, Zeitwerk, Marcel）。
• API 密钥: 需提前准备好对应模型服务商的 API Key（如 OpenAI, Anthropic, Google 等）。

提示：国内开发者若访问 RubyGems 源较慢，可临时切换至国内镜像源：

gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/

安装步骤

1. 添加依赖

在你的项目 Gemfile 中添加：

gem 'ruby_llm'

2. 安装 Gem

执行以下命令安装：

bundle install

3. 配置 API 密钥

在初始化文件（如 config/initializers/ruby_llm.rb 或项目入口文件）中配置密钥：

RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
  # 如需使用其他模型，也可配置对应 key，例如：
  # config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
end

基本使用

最简单的对话示例

只需三行代码即可发起对话：

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

多模态能力（图片/文件分析）

直接传入文件路径即可让 AI 分析图片、视频、音频或文档：

chat.ask "What's in this image?", with: "ruby_conf.jpg"
chat.ask "Summarize this document", with: "contract.pdf"

流式输出

通过代码块实时获取回复内容：

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

调用自定义工具 (Tools)

让 AI 调用你的 Ruby 方法（例如查询天气）：

class Weather < RubyLLM::Tool
  description "Get current weather"
  param :latitude
  param :longitude

  def execute(latitude:, longitude:)
    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
    JSON.parse(Faraday.get(url).body)
  end
end

chat.with_tool(Weather).ask "What's the weather in Berlin?"

Rails 集成（可选）

如果你使用的是 Rails 项目，可以使用生成器快速集成：

bin/rails generate ruby_llm:install
bin/rails db:migrate
bin/rails generate ruby_llm:chat_ui

然后在 Model 中启用：

class Chat < ApplicationRecord
  acts_as_chat
end

chat = Chat.create! model: "claude-sonnet-4"
chat.ask "What's in this file?", with: "report.pdf"

启动服务器后访问 http://localhost:3000/chats 即可使用内置的聊天界面。