rubyllm

RubyLLM で構築する

アプリケーションにインストールされている RubyLLM のバージョンと既存の規約を使用してください。このスキルでは 2.x API について説明します。2.1 と記載された機能には RubyLLM 2.1 以降が必要です。API を選ぶ前に、Gemfile.lock を読むか、インストール済みの gem を確認してください。

bundle exec ruby -rruby_llm -e 'puts RubyLLM::VERSION'
bundle show ruby_llm

1.x のアプリケーションでは、そのバージョンのドキュメントを使用し、ユーザーからアップグレードを依頼されない限り、変更の対象を 1.x のままにしてください。AI 機能を追加するために、アプリケーションのフレームワークをアップグレードする必要はありません。

タスクに応じて API を選ぶ

RubyLLM には、2 つの公開 API ファミリーがあります。会話には、チャット、メッセージ、ツール、エージェント、構造化出力、ストリーミング、ループ制御を使用します。個々の処理には、paint、animate、speak、transcribe、ocr、moderate、embed、rerank、judge、tokenize、research を使用します。個々の処理はチャットを必要とせず、型付きの結果を返します。ストリームを返すものや、非同期のライフサイクルを持つものもあります。

プロバイダーは、サービスのエンドポイント、認証、カタログ、プロトコルの選択を提供します。プロトコルはリクエストとレスポンスを変換します。どちらの API ファミリーも、この統合レイヤーと、モデル選択、設定、使用状況の記録、インストルメンテーションのための共有サービスを利用します。公開 API を使って構築し、サービスの形式への対応は RubyLLM に任せてください。

Rails 統合は、同じ Ruby API を基盤として、永続化、添付ファイル、ストリーミング UI のサポート、ジョブ、ジェネレーターを追加します。

関連する API を探す

インストール済み gem の公開メソッドのシグネチャと RDoc には、アプリケーションが実際に実行するコードが記載されています。オンラインドキュメントと異なる場合は、こちらを参照してください。RubyLLM のドキュメントで該当するバージョンを確認してください。ルートサイトには最新の安定版が掲載されています。main の未リリースの変更は rubyllm.com/next/ に、1.x は rubyllm.com/v1/ に掲載されています。

ドキュメントサイト全体を読み込むのではなく、関連するページを参照してください。

タスク	該当バージョンのドキュメント内のガイドパス
フレームワークの構成を理解する	overview/
プロバイダーを設定する、またはモデルを選択する	configuration/、configuration-providers/、models/
チャット、ストリーミング、ファイルの添付を行う	chat/、streaming/、attachments/
ツールを宣言する、または承認を必須にする	tools/、tool-parameters/、tool-execution/
添付ファイルや長いツールの結果を会話に含めないようにする（2.2）	chat-files/
MCP サーバーのツールを使用する（2.1）	mcp/
ウェブ検索など、プロバイダーがホストするツールを使用する	provider-tools/、citations/
構造化出力を解析する	structured-output/
再利用可能なエージェントを構築する	agents/、prompt-rendering/
思考機能やプロンプトキャッシュを有効にする	thinking/、prompt-caching/
画像や動画を生成する	image-generation/、video-generation/
音声を生成する、または音声を書き起こす	text-to-speech/、audio-transcription/
ドキュメントのテキストを抽出する、またはコンテンツをモデレートする	ocr/、moderation/
テキストを埋め込む、または検索結果をランク付けする	embeddings/、rerank/、rag/
型付きの回答で分類、採点、判断を行う（2.1）	judgments/
データセットを使って回答の品質を測定する（2.1）	evaluations/、evaluation-datasets/、evaluation-evaluators/、evaluation-running/、evaluation-examples/
トークンを数える、プロバイダーファイルをアップロードする、またはホスト型の調査を実行する	tokenization/、files/、hosted-research/
Hotwire でチャットを永続化する、ファイルを添付する、またはストリーミングする	rails/、rails-persistence/、rails-streaming/、rails-generators/、rails-advanced-config/
バックグラウンドジョブでエージェントを再開する	durable-agents/
支出を追跡する、または失敗を処理する	cost-and-usage-tracking/、error-handling/
呼び出しを監視する、ワークフローをグループ化する、または OpenTelemetry でトレースする	instrumentation/、opentelemetry/（2.1）
バッチを送信する、または会話ループを制御する	batches/、agentic-workflows/
既存のアプリケーションをアップグレードする	upgrading/

Markdown ガイドは、chat.md のように同じ名前に .md を付けたファイルです。API リファレンスは api/RubyLLM.md から始まります。クラスのリファレンスには api/RubyLLM/Chat.md と api/RubyLLM/Agent.md があります。ドキュメントを取得できない場合は、インストール済みのソースを調べ、残っている不確実な点を特定してください。

2.x API を一貫して使用する

• アプリケーションのシークレットストレージに従って、RubyLLM.configure で認証情報を設定します。既存の設定済みプロバイダーを選択します。明示的なモデル ID は RubyLLM.models.find(id, provider: ...) で検証してください。ID を作り出したり、入力ミスを隠すために assume_model_exists を使ったりしないでください。
• 会話には RubyLLM.chat を使います。連鎖可能な with_* メソッドでオプションを設定します。指示、ツール、オプションを再利用する場合は RubyLLM::Agent を使います。通常の Ruby メソッドやジョブを組み合わせてワークフローを構成します。
• メディア、ドキュメント処理、モデレーション、埋め込み、再ランキングには、個別の操作を直接使います。型付きの結果を読み取り、生成された画像、動画、音声には save を使います。各操作で利用するプロバイダー、モデル、認証情報を確認してください。設定済みのチャットプロバイダーが、すべての操作を提供するとは限りません。animate は完了まで待機します。アプリケーション側でジョブを管理する必要がある場合は animate_later を使います。
• ask は会話を実行してメッセージを返します。ask_later は入力をステージングしてチャットを返します。ループを明示的に制御するには、generate、run_tools、step、complete? を使います。承認待ちになると、完了前にループが一時停止する場合があります。awaiting_approval? を確認し、approve または deny の後に再開します。queue はループの実行中にユーザーメッセージを追加します（steer: false の場合はターンの終了を待ちます）。次の ask、complete、または step は、その時点でキューに残っているものをすべて処理します。
• テキストは message.content から、構造化出力は message.parsed から読み取ります。スキーマは Schematist::Schema またはスキーマ DSL で宣言します。content がパース済みの Hash だと想定しないでください。
• RubyLLM::Tool をサブクラス化します。description、parameter、または parameters ブロックを使い、execute にはキーワード引数を使います。with_tools でツールを登録し、with_tool_options で選択方法と並行実行を設定します。アプリケーションの認可はツールまたは基盤となるサービスで維持してください。実行前にユーザーの判断が必要な場合は requires_approval を使います。ツールの数が多い場合は、with_tools または with_mcp に defer: true を渡す（またはクラスで defer を宣言する）ことで、モデルがすべてのツールを受け取るのではなく、ツールを検索するようにします（2.1）。
• with_thinking、with_caching、with_compaction、with_citations は引数なしで有効にし、false で無効にします。これらは nil を拒否します。対応オプションとモデル要件については、該当するガイドを参照してください。
• 添付ファイルやツールの結果が大きい場合は、プロンプトにテキストを貼り付けるのではなく、with_file_store（またはエージェントの file_store マクロ）を使います（2.2）。モデルは独自のツールでファイルを読み取り、検索します。ストアは chat.file_store です。RubyLLM.file_store.memory または .directory(path) でストアを構築します。標準ではテキストファイルのみがテキストとして読み取られます。PDF や画像向けの RubyLLM.file_store.converter.ocr など、対象を増やすには config.file_converters を登録します。
• RubyLLM::MCP をサブクラス化して MCP サーバーに接続します（url または command を指定し、続いて only と requires_approval でツールを調整します）。chat.with_mcp(...) またはエージェントの mcp マクロで接続します（2.1）。別途 MCP クライアント gem を追加しないでください。
• アプリケーションデータについて、はい／いいえの確率、選択肢、またはスコアが必要な場合は、RubyLLM::Judge をサブクラス化して .judge(input) を呼び出します。チャットからの自由形式テキストをパースしないでください（2.1）。バックエンドには TypeSafe の Jev、OpenAI Decisions、provider: :ollama を指定した Clef などのローカル判定モデルがあります。
• 代替モデルには with_fallbacks、プロバイダー提供のツールには with_provider_tools を使います。長時間実行されるツールの進捗を報告するには、ツール内で progress を使い、チャットで after_tool_progress を設定します（2.1）。
• テナントごとの認証情報やエンドポイントには RubyLLM.context を使います。設定がエージェントの入力に依存する場合は、エージェントの context ブロックを使います（2.1）。
• 利用可能な場合は、RubyLLM 共通のオプションを使います。provider_options はプロバイダー固有のリクエストフィールド用に限定します。RubyLLM がすでに提供する機能のために、別のプロバイダー SDK を追加しないでください。
• トークン数は message.tokens.input、.output、.cache_read、.cache_write、.thinking から読み取ります。コストは message.cost.total から読み取ります。不明なコストはゼロではなく nil です。台帳には個別の試行が含まれ、成功した応答にも以前の失敗した試行が含まれる場合があります。個別の操作で owner: を指定するか、RubyLLM.with_usage_owner を使って使用量を割り当てます（2.1）。永続化されたチャットの使用量には、チャットと所有者の両方への関連付けが保持されます。
• 関連する呼び出しを RubyLLM.workflow と workflow.step でまとめると、計測できます。既存の OpenTelemetry セットアップにトレースを送信するには、SDK の設定後に RubyLLM::OpenTelemetry.enable を呼び出します（2.1）。RubyLLM が SDK やエクスポーターを設定することはなく、プロンプトや応答をエクスポートすることもありません。
• RubyLLM の列挙値は Symbol です。finish_reason == :stop、思考の強度は :high です。プロバイダーのスラッグとモデル ID は String のままです。

Rails との統合

新しく統合する場合は、bin/rails generate ruby_llm:install を使用し、マイグレーションを確認して、アプリケーションのマイグレーション手順に従ってください。パッケージに含まれるモデルデータは bin/rails ruby_llm:load_models で読み込みます。RubyLLM.models.refresh はネットワーク経由で更新し、その結果を永続化します。

チャットモデルとメッセージモデルはアプリケーション側で所有し、acts_as_chat と acts_as_message で宣言します。RubyLLM は、サポート用のモデル、ツール呼び出し、使用量、バッチ用のテーブルに加え、2.1 以降の MCP 認証情報とプロバイダーファイル用のテーブルを所有します。1.x の例をもとに、アプリケーションの Model クラスや ToolCall クラスを生成しないでください。アプリケーションで異なる名前を使っている場合は、ジェネレーターにカスタムのチャットとメッセージのマッピングを渡してください。

永続化されたレコードでも、同じチャット API を使用します。永続化されたレコードに対する ask は、アプリケーションのメッセージレコードを返します。バックグラウンド処理には既存のジョブバックエンドを使用してください。別のプロセスでジョブを再開する場合は、文書化されている永続化 API を使ってエージェントを取得し、設定してください。慣例として、プロンプトテンプレートは app/prompts の下に配置します。

Active Storage の添付ファイルは with: で渡し、インストール用ジェネレーターが設定するメッセージの添付ファイル関連付けを維持してください。Hotwire の UI には、Rails のストリーミングガイドまたは ruby_llm:chat_ui ジェネレーターを使用してください。永続化されたメッセージが Turbo Streams のターゲットになります。個々の操作は、通常の Ruby と同じメソッドを使って Rails のサービスやジョブから直接実行できます。

ブラウザーに返信をストリーミングする場合は、各チャンクを一度だけブロードキャストし、エスケープしたテキストとしてメッセージのコンテンツ要素に追加してから、返信が完了した時点でメッセージを一度だけ置き換えます。最後の置き換えにより、順序が入れ替わって届いたチャンクや、要素が存在する前に届いたチャンクを修正できます。チャンクごとに累積テキストや再レンダリングした HTML を再送信しないでください。送信バイト数が返信の長さの二乗に比例して増加します。チャンクごとにサーバー上で Markdown をレンダリングしないでください。ストリーミング中に表示する場合は、チャンクに番号を付け、チャット UI ジェネレーターの Stimulus コントローラーと同様に、ストリーミングしたテキストをブラウザーでサニタイズしてレンダリングしてください。それ以外の場合は、最後の置き換え時にのみレンダリングします。

アップグレードする場合は、マイグレーションを編集する前に、該当するアップグレードガイドを最初から最後まで読んでください。各リリースのアップグレードに含まれるのは、直前のリリースからの変更のみです。そのため、一度に1リリースずつアップグレードしてください。1.x のアプリケーションでは、まず 2.0 へのアップグレードを完了します。2.0 への移行では、影響を受ける処理を再開する前に、準備、バックフィル、完了、およびアプリケーション固有の調整が必要です。レガシーカラムのクリーンアップは後の段階で行います。チェックポイントがあるため、中断したバックフィルは再開できます。カラムが残っていても、1.x のコードへ安全にロールバックできるわけではありません。隔離したスナップショットでリハーサルを行い、アプリケーションのデプロイおよび復旧手順を遵守してください。

AI の動作を評価する

スペックではコードをチェックし、評価ではモデルがどれくらいの頻度で正解するかをチェックします（2.1）。app/evals に RubyLLM::Evaluation のサブクラスとそのデータセットを配置し、クラス名に合わせて名前を付けます（support_evaluation.rb と support_evaluation.yml）。perform(input) はアプリケーションを実行し、文字列、Message、Chat、または Agent を返します。各ケースには name、inputs、通常は expected_output を指定します。

• 基準を宣言していない場合、モデルは各回答を expected_output と照合します。その場合は、すべてのケースに expected_output を指定する必要があります。evaluation :name, "statement" で基準を宣言すると、既定の評価が置き換わります。説明を付けずに evaluation :correctness とすると、既定の評価が維持されます。
• assertions は、output、tool_calls、messages、input、expected_output、metadata を使った Minitest アサーションを実行します。アサーションを使っても採点は無効になりません。無効にするには evaluator false を指定します。Rails の外部では、アサーションを使うために gem "minitest" が必要です。
• evaluator model: ...、Agent クラス、または evaluation :name, minimum: 0.8 を指定した Judge クラスで、採点者を選択します。
• bin/rails "ruby_llm:eval[SupportEvaluation]"、SupportEvaluation.run、または RSpec や Minitest で evaluates SupportEvaluation を実行します。その前に RubyLLM::Evaluation::RSpec または RubyLLM::Evaluation::Minitest を拡張してください。モデルによる採点には実行のたびに費用がかかるため、アプリケーションでリクエストを記録している場合を除き、採点を伴う評価を既定のテスト実行から除外してください。

アプリケーションの変更を検証する

アプリケーションに関連するテストを実行してください。変更内容に応じて、ツールのビジネスロジック、構造化データの解析、会話の永続化データからの再構築、ジョブの再開をテストします。必要に応じて、アプリケーション既存の記録機能または統合テストのセットアップを使ってモデル呼び出しを検証し、実際にテストしたプロバイダーの動作を報告してください。実装は、依頼された機能と既存のアプリケーションアーキテクチャの範囲内に収めてください。