ruby_llm-agents 仓库中文介绍文档

ruby_llm-agents 是一个基于 Ruby 的生产就绪型 Rails 框架，用于构建、管理和监控 LLM 驱动的 AI 代理，由 adham90 提供，支持提示、模式、缓存、日志记录、成本跟踪和内置仪表板等功能，汇聚了对 OpenAI GPT-4、Anthropic Claude、Google Gemini 等多种 LLM 提供商的支持。

要点：

这是一个用于构建 AI 代理的 Rails 框架
解决了在生产环境中管理 LLM 使用的问题
包含 Stars 数（如需）

示例： OpenBB 是一款面向金融分析师、量化交易员与 AI 智能体的开源金融数据平台，以"一次连接、随处消费"为核心架构，统一接入股票、期权、加密等多资产数据。

一、核心信息速览

维度	详情
:---	:---
仓库地址	[ruby_llm-agents](https://github.com/adham90/ruby_llm-agents)
许可证	MIT License
核心定位	用于构建、管理和监控 LLM 驱动的 AI 代理
主要语言	Ruby
适用人群	Rails 开发者；LLM 应用开发者；需要监控 LLM 成本的团队
关键亮点	生产就绪；Rails 原生集成；全面可观测性；零锁定

二、核心功能

功能模块	描述	典型场景
:---	:---	:---
AI 代理框架	提供结构化 DSL 来定义 AI 代理	构建智能对话系统
执行追踪	自动记录每次执行的成本、令牌数、持续时间	监控 LLM 调用情况
成本分析	提供详细的成本统计和预算控制	控制 LLM 使用成本
实时仪表板	内置实时监控界面	实时查看代理运行状态
模型回退	支持模型失败后的自动回退机制	提升系统可靠性
语义搜索	支持向量嵌入用于语义搜索	构建 RAG 系统
日志记录	自动记录所有操作日志	便于调试和审计
缓存支持	提供缓存机制优化性能	减少重复调用

三、快速上手

1. 环境准备

Ruby 3.0 或更高版本，以及 Ruby on Rails 7.0 或更高版本

2. 安装方式

gem install ruby_llm-agents

3. 基础配置

将 ruby_llm-agents 添加到 Gemfile 并运行 bundle install，然后生成配置文件：

rails generate ruby_llm_agents:install

4. 核心示例

class SearchIntentAgent < ApplicationAgent
  model "gpt-4o"
  temperature 0.0

  system "You are a search intent analyzer. Extract structured data from queries."
  user "Extract search intent from: {query}"
  assistant '{"refined_query":'  # Force JSON output

  returns do
    string :refined_query, description: "Cleaned search query"
    array :filters, of: :string, description: "Extracted filters"
  end
end

result = SearchIntentAgent.call(query: "red summer dress under $50")

result.content        # => { refined_query: "red dress", filters: ["color:red", "price:<50"] }
result.total_cost     # => 0.00025
result.total_tokens   # => 150
result.duration_ms    # => 850

四、核心亮点

生产就绪：内置重试、模型回退、断路器和预算限制，适合生产环境。
Rails 原生集成：无缝集成到 Rails 应用中，支持模型、作业、缓存和 Hotwire。
全面可观测性：跟踪每一次执行的成本、令牌数、持续时间和错误。
零锁定：兼容任何 RubyLLM 支持的 LLM 提供商。

五、适用场景

构建 AI 代理：为应用程序添加智能行为，如查询解析、代码生成等。
成本控制：监控并控制 LLM 使用成本，防止意外支出。
实时监控：通过内置仪表板实时查看代理运行状态。
高可用系统：利用重试、回退和断路器机制提高系统的稳定性。

六、优缺点

优势

提供完整的 AI 代理开发框架
易于与 Rails 集成
支持多种 LLM 提供商

不足

文档可能不够详细
对非 Ruby 项目支持有限

七、与同类工具对比（可选）

工具	类型	核心差异
:---	:---	:---
本工具	开源框架	支持 Rails 原生集成，提供完整可观测性和成本控制
LangChain	Python 框架	适用于 Python 项目，生态丰富但不支持 Rails