RubyLLM: A Ruby framework for all major AI providers

Who Should Read

Ruby/Rails 기반 서비스에 AI 기능(챗봇, RAG, 에이전트, 이미지 분석 등)을 추가하려는 백엔드 개발자. 여러 AI 프로바이더 SDK를 각각 다루는 게 번거로워서 통합 인터페이스를 찾고 있는 상황에 특히 유용하다.

Core Mechanics

• RubyLLM은 OpenAI, Anthropic(Claude), Google Gemini, xAI, DeepSeek, Mistral, Ollama, OpenRouter, Perplexity, AWS Bedrock, VertexAI, GPUStack 등 주요 AI 프로바이더를 단일 인터페이스로 감싸서, 어떤 모델을 쓰든 같은 코드 패턴으로 호출할 수 있다.
• 채팅, 이미지 분석(Vision), 오디오 전사(Transcription), 이미지 생성, 임베딩(텍스트를 숫자 벡터로 변환), 콘텐츠 모더레이션까지 AI의 주요 기능을 모두 커버한다. `RubyLLM.chat`, `RubyLLM.paint`, `RubyLLM.embed`, `RubyLLM.transcribe` 같은 직관적인 메서드로 바로 쓸 수 있다.
• 파일을 `with:` 옵션으로 넘기면 이미지(.jpg), 비디오(.mp4), 오디오(.wav), PDF, CSV, 코드 파일(.rb) 등 다양한 파일 타입을 AI에게 분석시킬 수 있고, 여러 파일을 배열로 한 번에 넘기는 것도 된다.
• Tool(도구) 기능을 통해 Ruby 클래스를 정의하면 AI가 직접 그 코드를 호출하게 할 수 있다. 예를 들어 `Weather < RubyLLM::Tool`을 만들면 AI가 날씨 API를 스스로 호출해서 답변한다.
• Agent 기능은 `RubyLLM::Agent`를 상속해서 모델, 지시문(instructions), 사용할 Tool을 선언하면 재사용 가능한 AI 어시스턴트를 클래스 형태로 만들 수 있다. 이 방식으로 복잡한 Agentic 워크플로우를 구성할 수 있다.
• Structured Output 기능으로 `RubyLLM::Schema`를 상속해 스키마를 정의하면 AI 응답을 원하는 JSON 구조로 받을 수 있다. 타입(string, number, array 등)을 명시적으로 선언하는 방식이다.
• Rails 통합이 잘 되어 있어서 `acts_as_chat`을 ActiveRecord 모델에 추가하면 대화 내역을 DB에 자동으로 저장하고, `rails generate ruby_llm:chat_ui`로 바로 쓸 수 있는 채팅 UI까지 생성된다.
• 의존성이 Faraday(HTTP 클라이언트), Zeitwerk(자동 로딩), Marcel(파일 타입 감지) 딱 세 개뿐이라 불필요한 패키지 부담이 없다. 현재 버전은 1.16.0이고 2.0 개발 버전도 진행 중이다.

Evidence

• Vercel의 AI SDK(JavaScript 생태계의 AI 통합 프레임워크)와 사용성이 비슷한 수준이라는 긍정적 평가가 있었다. 단, xAI 같은 일부 프로바이더에서 캐시가 제대로 작동하지 않는 실제 고통 포인트도 공유됐다 — xAI가 completions API만 지원하고 thought signature 반환이 잘못되는 문제 때문이다.
• Responses API(OpenAI의 최신 API 방식)가 기본 지원되지 않는다는 불만이 있었고, 다른 개발자가 만든 커넥터는 버그가 많아서 메인 gem 품질에 못 미친다는 의견이 있었다. 다만 최근에 Responses API 네이티브 지원이 추가된 것 같다는 업데이트가 달렸다.
• 프로덕션 관찰성(Observability) 측면에서 트레이스 계측이 어렵다는 단점이 지적됐다. 또한 재시도 로직이 내부 모델을 삭제해버려서 대화 히스토리가 겉으로는 깔끔해 보이지만 실제 API 호출 순서를 파악하기 어렵다는 경험담이 공유됐다.
• Claude만 쓰고 Anthropic 생태계에서 벗어날 계획이 없는 경우 직접 Anthropic Ruby SDK를 쓰는 것 대비 RubyLLM이 어떤 이점이 있냐는 질문이 있었다. Fog vs aws-sdk-s3(낮은 수준 통합)냐, Active Storage vs aws-sdk-s3(고수준 추상화)냐는 비유로 포지셔닝을 물어보는 실용적인 관점이었다.
• temperature, effort, max_tokens 같은 모델별 파라미터를 세밀하게 조정하려면 결국 플랫폼 특화 설정을 직접 건드려야 한다는 단점이 언급됐다. 완전한 추상화가 아니라는 점에서 아쉬움이 있다는 평가다.

How to Apply

• Rails 앱에 AI 챗봇 기능을 추가하려는 경우, `gem 'ruby_llm'` 추가 후 `rails generate ruby_llm:install`과 `rails generate ruby_llm:chat_ui`를 실행하면 DB 마이그레이션과 채팅 UI까지 자동으로 세팅된다. `acts_as_chat`을 모델에 추가하면 대화 내역이 ActiveRecord로 자동 영속화된다.
• 여러 AI 프로바이더를 비교하거나 상황에 따라 다른 모델을 써야 하는 경우, RubyLLM의 단일 인터페이스를 사용하면 `chat = RubyLLM.chat(model: 'claude-sonnet-4')` 처럼 모델만 바꿔서 코드 변경 없이 프로바이더를 전환할 수 있다.
• AI가 외부 API나 DB를 조회해서 답변해야 하는 서비스를 만드는 경우, `RubyLLM::Tool`을 상속한 클래스에 `execute` 메서드를 구현하고 `chat.with_tool(MyTool).ask '질문'` 형태로 연결하면 Function Calling(AI가 코드를 직접 호출) 기능을 바로 붙일 수 있다.
• AI 응답을 구조화된 데이터로 파싱해야 하는 경우(예: 상품 정보 추출, 문서 분류 등), `RubyLLM::Schema`로 원하는 필드와 타입을 선언하고 `chat.with_schema(MySchema).ask '...'`를 쓰면 JSON 파싱 로직을 별도로 작성하지 않아도 된다.

Code Example

# 기본 채팅
chat = RubyLLM.chat
chat.ask "What's the best way to learn Ruby?"

# 파일 분석 (이미지, PDF, 오디오 등)
chat.ask "Summarize this document", with: "contract.pdf"
chat.ask "Analyze these files", with: ["diagram.png", "report.pdf"]

# 스트리밍 응답
chat.ask "Tell me a story" do |chunk|
  print chunk.content
end

# Tool 정의 (AI가 Ruby 코드를 직접 호출)
class Weather < RubyLLM::Tool
  desc "Get current weather"
  def execute(latitude:, longitude:)
    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m"
    JSON.parse(Faraday.get(url).body)
  end
end
chat.with_tool(Weather).ask "What's the weather in Berlin?"

# Agent 정의
class WeatherAssistant < RubyLLM::Agent
  model "gpt-5-nano"
  instructions "Be concise and always use tools for weather."
  tools Weather
end
WeatherAssistant.new.ask "What's the weather in Berlin?"

# Structured Output
class ProductSchema < RubyLLM::Schema
  string :name
  number :price
  array :features do
    string
  end
end
response = chat.with_schema(ProductSchema).ask "Analyze this product", with: "product.txt"

# Rails 통합
class Chat < ApplicationRecord
  acts_as_chat
end
chat = Chat.create! model: "claude-sonnet-4"
chat.ask "What's in this file?", with: "report.pdf"

# 설정
RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
end

Terminology

Related Papers

• Qwen-AgentWorld: Language World Models for General Agents

  Alibaba Qwen 팀이 AI 에이전트가 행동 결과를 미리 시뮬레이션할 수 있는 'Language World Model'을 공개했다. 에이전트 훈련과 실행 경로 검증에 새로운 패러다임을 제시하는 연구다.

• SHERLOC: Structured Diagnostic Localization for Code Repair Agents

  버그 위치만 알려주는 게 아니라 '왜, 어떻게 고쳐야 하는지'까지 진단 리포트를 생성해서 코드 수정 에이전트의 성능을 높이는 training-free 프레임워크

• Show HN: peerd – AI agent harness that runs entirely in your browser

  백엔드 서버 없이 Chrome/Firefox 확장 프로그램으로만 동작하는 AI 에이전트 실행 환경으로, 브라우저 탭을 직접 조작하고 WASM Linux VM까지 구동할 수 있어 프라이버시와 보안을 동시에 챙길 수 있다.

• SAFARI: Scaling Long Horizon Agentic Fault Attribution via Active Investigation

  수백만 토큰 넘는 에이전트 실행 로그에서 버그 발생 지점을 찾아내는 도구 기반 진단 프레임워크

• Self-Compacting Language Model Agents

  LLM 에이전트가 스스로 '지금 요약해도 되는지'를 판단하는 rubric을 추가하면, 파인튜닝 없이도 고정 주기 요약보다 정확도는 높고 비용은 30~70% 낮아진다.

• Show HN: Oak – Git alternative designed for agents

  AI 에이전트가 코드 작업을 더 효율적으로 수행할 수 있도록 설계된 새로운 버전 관리 시스템(VCS)으로, lazy mount, JSON-first CLI, 멀티 레포 에이전트 워크스페이스 등을 제공한다. 다만 커뮤니티에서는 Git 대비 실질적 우위가 충분히 증명되지 않았다는 회의적 반응이 많다.

Related Resources

• RubyLLM 공식 문서
• RubyLLM GitHub
• Raix - RubyLLM 기반 오픈소스 gem
• Legate - Ruby 기반 에이전트 개발 키트
• RailsChat - RubyLLM으로 만든 ChatGPT 클론
• SF Ruby Conf RubyLLM 발표 영상
• Laravel AI SDK (유사 프레임워크 참고)