用Rails打造AI助手：RubyLLM實戰指南

　　在Rails應用里集成大語言模型，開發者通常面臨一個選擇：用現成的AI服務，還是自建可定制的智能代理？RubyLLM這個gem給出了第三條路——它讓你用幾十行代碼就能搭出可復用的聊天型AI助手，既保留對模型和提示詞的控制權，又不必處理底層的API對接細節。

　　聊天型代理（Chat-based agents）和Claude Code、Codex這類全自動代理有本質區別。前者在每次交互中保持明確的上下文邊界，開發者可以精確控制工具調用時機和返回格式；后者則傾向于自主決策，適合探索性任務但難以預測行為。對于需要嵌入現有業務流程、輸出格式必須穩定的場景，聊天型代理往往是更務實的選擇。

　　開始之前，先完成環境準備。安裝gem后，在config/initializers/rubyllm.rb中配置API密鑰：

　　require 'rubyllm'

　　RubyLLM.configure do |config|
config.api_key = ENV['OPENAI_API_KEY']
end

　　這里把密鑰放進環境變量是基本操作，避免敏感信息進代碼倉庫。配置塊采用標準的Ruby DSL風格，熟悉Rails初始化流程的開發者不會感到陌生。

　　接下來定義代理類。RubyLLM::Agent作為基類，已經封裝了模型調用、消息歷史管理、工具注冊等通用邏輯。你的子類只需要關注業務層面的定制：

　　# app/models/chat_agent.rb
require 'rubyllm'

　　class ChatAgent < RubyLLM::Agent
def initialize
super('text-davinci-003')
end

　　 def respond(message)
# 在這里實現自定義邏輯
message
end
end

　　初始化時傳入的'text-davinci-003'指定了底層模型，respond方法則是交互入口。這種設計把"選什么模型"和"怎么處理輸入"解耦，方便后續切換模型版本或調整業務規則。

　　更復雜的配置需求可以單獨抽離。RubyLLM::Configuration子類允許你在代理實例化后動態注入參數——比如根據用戶權限調整溫度系數，或者按業務線切換不同的系統提示詞：

　　# app/models/chat_agent_config.rb
class ChatAgentConfig < RubyLLM::Configuration
def initialize(agent)
super
@agent = agent
end

　　 def configure(agent)
# 在這里設置自定義配置
end
end

　　配置類與代理類的分離遵循了單一職責原則。當產品需求變成"企業版用戶用GPT-4、免費版用GPT-3.5"時，你只需要修改配置層，代理的核心邏輯完全不用動。

　　把代理接入Rails控制器很直接。一個典型的create動作如下：

　　# app/controllers/chats_controller.rb
class ChatsController < ApplicationController
def create
chat_agent = ChatAgent.new
response = chat_agent.respond(params[:message])
render json: { response: response }
end
end

　　這里有個值得注意的設計決策：每次請求都新建代理實例。這樣做的好處是請求之間完全隔離，不會出現A用戶的消息歷史混入B用戶對話的情況。如果性能敏感，可以考慮用對象池或單例模式配合線程安全的上下文管理，但需要額外處理并發下的狀態隔離。

　　RubyLLM的agent架構本質上是對"增強型LLM"這一概念的工程化封裝。所謂增強，指的是在裸模型之外疊加了三層能力：工具調用接口（讓模型能查數據庫、調API）、運行時上下文（注入當前用戶信息、業務狀態）、提示詞約定（固化角色設定和輸出格式）。這三層都通過聲明式配置完成，不需要寫復雜的編排代碼。

　　實際部署時，建議關注幾個實踐要點。模型選擇要平衡能力與成本，text-davinci-003在代碼生成場景表現穩定，但如果是多輪對話可能需要切換到聊天優化過的模型。提示詞工程盡量前置到配置層，避免在respond方法里拼接字符串。工具注冊遵循最小權限原則，每個工具函數都要校驗輸入參數，防止模型幻覺導致意外副作用。

　　這套方案的價值在于"漸進式增強"。你可以從最簡單的echo代理開始，逐步添加數據庫查詢工具、用戶畫像注入、輸出格式校驗，每一步都有明確的擴展點。相比直接調用OpenAI API的裸奔方案，RubyLLM提供了符合Rails慣例的抽象層；相比引入LangChain這類重型框架，它又保持了足夠的輕量和可控。

　　對于已經在Rails技術棧深耕的團隊，這種"原生感"很重要。不需要學習新的配置語法，不需要處理異構的部署流程，AI能力像Active Record或Sidekiq一樣自然融入現有架構。當產品經理說"我們想在客服工單系統里加個智能分類"時，你可以在一個控制器動作里搞定原型，而不是立項調研三個月。