API連携は、動かすだけなら難しくない
RubyやRailsからOpenAI APIを呼び出すこと自体は、そこまで難しくありません。
APIキーを用意して、HTTPリクエストを送り、返ってきたテキストを画面やDBに保存する。
最小構成なら、思ったより早く動きます。
ただ、アプリに組み込むとなると、見るべき場所が増えます。
キーの管理、エラー時の扱い、ログ、料金、タイムアウト、ユーザーにどう見せるか。
ここを決めずに進めると、あとから不安が残ります。
今回は、RubyでOpenAI APIを使うときに、自分なら最初に見る点を整理します。
APIキーはコードに書かない
まず大前提として、APIキーはコードに直接書かないほうがよいです。
Railsなら、環境変数やcredentialsで管理します。
本番環境ではRenderなどの環境変数に入れ、ローカルでは .env やcredentialsを使う形が多いと思います。
重要なのは、キーがGitに入らないことです。
client = OpenAI::Client.new(
access_token: Rails.application.credentials.dig(:openai, :api_key)
)
このように、コード側では「どこから読むか」だけを決め、実際の値は外に置きます。
セキュリティの考え方は 「除外」より「許可」。セキュアで読みやすいコードにする にも近いです。
危ない値を混ぜない仕組みにしておくほうが、あとから気をつけるより安定します。
呼び出し処理は一箇所に寄せる
API呼び出しを各ControllerやJobに直接書くと、あとから変更しづらくなります。
モデル名を変えたい。
タイムアウトを足したい。
ログを増やしたい。
エラー時の挙動を変えたい。
こういう変更が出たとき、呼び出し箇所が散らばっているとつらくなります。
最初は小さくてよいので、専用クラスに寄せるのが扱いやすいです。
class OpenAiTextGenerator
def initialize(client: default_client)
@client = client
end
def call(prompt:)
@client.responses.create(
model: "gpt-4.1-mini",
input: prompt
)
end
private
def default_client
OpenAI::Client.new(
access_token: Rails.application.credentials.dig(:openai, :api_key)
)
end
end
実際に使うモデル名やAPI仕様は変わるので、公式の OpenAI API documentation を確認しながら合わせるのがよさそうです。
エラー時にユーザーを放置しない
AI APIは外部サービスなので、失敗する前提で見ておく必要があります。
- タイムアウト
- レート制限
- APIキーの設定漏れ
- 一時的な障害
- 入力が長すぎる
こういう失敗が起きたとき、ユーザーに何も返らないと体験が悪くなります。
「生成に失敗しました。時間を置いて再度お試しください。」
のように、最低限の案内を返せるようにしておきたいです。
同時に、開発者側には原因を追えるログが必要です。
ただし、プロンプトや個人情報をそのまま全部ログに出すのは危険です。
何をログに残すかも、最初に決めておくと安心です。
料金と実行時間も仕様に入れる
AI連携は、機能として動くかだけではなく、どれくらい使われるかも見ます。
1回あたりの入力が長い。
ユーザーが何度も再生成する。
バックグラウンドで大量に走る。
こうなると、料金や待ち時間が問題になります。
最初は、次のような制限を入れておくと扱いやすいです。
- 入力文字数の上限
- 1ユーザーあたりの実行回数
- タイムアウト秒数
- 失敗時の再試行回数
- 生成結果の保存方針
これはケチる話ではなく、アプリを安定して運用するための設計です。
まとめ
RubyでOpenAI APIを呼ぶこと自体は、入口としては始めやすいです。
ただ、アプリに組み込むなら、
キー管理、呼び出し箇所、エラー処理、ログ、料金、待ち時間まで含めて設計したいです。
AI機能は、動いた瞬間がゴールではありません。
ユーザーが安心して使えて、運用する側も追える状態にして初めて、アプリの機能として育っていきます。
まずは小さく動かしつつ、後から困りそうな場所だけ先に押さえておきたいと思います。