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

• Show HN: ctx – Search the coding agent history already on your machine

  Claude Code, Cursor, Codex 등 코딩 에이전트가 이전 세션의 논의·결정·실패 시도를 잊지 않도록 SQLite로 인덱싱해 재사용할 수 있게 해주는 오픈소스 CLI 도구다.

• Micro-Agent: Beat Frontier Models with Collaboration Inside Model API

  vLLM 팀이 단일 모델 API 호출 뒤에서 여러 모델이 협업하는 'Micro-Agent' 개념을 공개했습니다. 별도의 에이전트 코드 없이 라우터 레이어에서 모델 조합을 실행해 GPT-4급 결과를 더 저렴하게 낼 수 있다는 아이디어입니다.

• Ornith-1.0: self-improving open-source models for agentic coding

  Gemma 4와 Qwen 3.5를 기반으로 파인튜닝한 코딩 특화 오픈소스 모델로, RL(강화학습)을 통해 스캐폴드(에이전트 실행 구조)까지 함께 최적화하는 방식을 주장하지만, 커뮤니티에서는 벤치마크 과최적화에 불과하다는 의심을 받고 있다.

• Entity Binding Failures in Tool-Augmented Agents

  AI 에이전트가 올바른 도구를 선택해도 잘못된 대상에 실행하는 'Entity Binding 실패' 문제를 정의하고, 이를 막는 실행 정책을 평가한 논문.

• Herdr: Agent multiplexer that lives in your terminal

  여러 AI 코딩 에이전트(Claude, Codex 등)를 하나의 터미널에서 동시에 실행·관리할 수 있는 Rust 기반 오픈소스 툴로, tmux처럼 세션이 유지되고 SSH로 원격 접속도 가능해 멀티 에이전트 워크플로우를 크게 단순화해준다.

• Ornith-1.0: Self-scaffolding LLMs for agentic coding

  모델이 문제 풀이 전략(scaffold)을 직접 생성하고 개선하는 자기강화 학습 프레임워크를 적용한 오픈소스 코딩 특화 LLM으로, 9B 소형 모델부터 397B 대형 모델까지 라인업을 갖추고 SWE-Bench 등 주요 벤치마크에서 Claude Opus 4.7을 능가하는 성능을 보여줬다.

Related Resources

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