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 有两类公共 API：对话使用 chats、messages、tools、agents、structured output、streaming 和 loop control；单次操作使用 paint、animate、speak、transcribe、ocr、moderate、embed、rerank、judge、tokenize 和 research。单次操作会返回类型化结果，无需使用 chat。有些操作支持流式处理或具有异步生命周期。

提供方提供服务端点、身份验证、目录和协议选择。协议负责转换请求和响应。两类 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/
构建可复用的 Agent	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/
在后台作业中恢复 Agent	durable-agents/
跟踪开支或处理故障	cost-and-usage-tracking/、error-handling/
监控调用、对工作流分组或使用 OpenTelemetry 跟踪（2.1）	instrumentation/、opentelemetry/
提交批次或驱动对话循环	batches/、agentic-workflows/
升级现有应用	upgrading/

Markdown 指南使用相同名称并加上 .md，例如 chat.md。API 参考从 api/RubyLLM.md 开始；类参考包括 api/RubyLLM/Chat.md 和 api/RubyLLM/Agent.md。如果无法获取文档，请检查已安装的源码，并确认还有哪些不确定之处。

始终使用 2.x API

• 通过 RubyLLM.configure 配置凭据，并遵循应用的密钥存储方式。选择已配置的提供方。使用 RubyLLM.models.find(id, provider: ...) 验证明确指定的模型 ID；不要编造 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（或 Agent 的 file_store 宏），不要将文本粘贴到提示词中（2.2）：模型会使用自己的工具读取和搜索文件，chat.file_store 即为该存储。使用 RubyLLM.file_store.memory 或 .directory(path) 创建存储。默认情况下，只有文本文件会作为文本读取；如需处理更多类型，请注册 config.file_converters，例如用于 PDF 和图像的 RubyLLM.file_store.converter.ocr。
• 通过继承 RubyLLM::MCP 连接 MCP 服务（使用 url 或 command，再通过 only 和 requires_approval 筛选工具），并使用 chat.with_mcp(...) 或 Agent 的 mcp 宏连接（2.1）。不要额外添加单独的 MCP 客户端 gem。
• 若要判断应用数据的概率、选项或评分，请继承 RubyLLM::Judge 并调用 .judge(input)，而不是解析聊天中的自由文本（2.1）。后端包括 TypeSafe 的 Jev、OpenAI Decisions，以及 Clef 等本地决策模型（使用 provider: :ollama）。
• 使用 with_fallbacks 指定备用模型，使用 with_provider_tools 指定由提供方托管的工具；在长时间运行的工具中使用 progress，并在聊天对象上配合 after_tool_progress 报告进度（2.1）。
• 使用 RubyLLM.context 配置每个租户的凭据或端点；当配置取决于 Agent 的输入时，请使用 Agent 的 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。提供方 slug 和模型 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 获取并配置 Agent。按照惯例，提示词模板位于 app/prompts 下。

通过 with: 传递 Active Storage 附件，并保留安装生成器设置的消息附件关联。对于 Hotwire UI，请使用 Rails 流式传输指南或 ruby_llm:chat_ui 生成器：持久化消息会为 Turbo Streams 提供目标。单独的操作可直接在 Rails 服务和任务中执行，使用的方法与纯 Ruby 相同。

向浏览器流式传输回复时，每个数据块只广播一次，并将其作为转义文本追加到消息的内容元素中；完成后再替换一次消息。最终替换可以修复乱序到达或在元素尚不存在时到达的数据块。切勿在每个数据块上重新发送累积文本或重新渲染的 HTML：发送的字节数会随着回复长度的平方增长。切勿在服务器上逐块渲染 Markdown。若要在流式传输期间显示 Markdown，请为数据块编号，并像聊天 UI 生成器的 Stimulus 控制器那样，在浏览器中对流式文本进行净化后再渲染；否则，只在最终替换时渲染。

升级时，请在编辑迁移之前阅读完整的对应升级指南。每个版本的升级指南只涵盖相较于上一版本的更改，因此请一次升级一个版本；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 进行比较，此时每个用例都必须提供该字段。evaluation :name, "statement" 会声明评估标准并替代默认标准；不带说明的 evaluation :correctness 则会保留默认标准。
• assertions 使用 Minitest 断言，并提供 output、tool_calls、messages、input、expected_output 和 metadata。断言不会关闭评分；evaluator false 才会关闭。在 Rails 之外，断言需要 gem "minitest"。
• 使用 evaluator model: ...、Agent 类或 Judge 类来选择评分器，并使用 evaluation :name, minimum: 0.8 设置最低分。
• 使用 bin/rails "ruby_llm:eval[SupportEvaluation]"、SupportEvaluation.run 运行；也可以在扩展 RubyLLM::Evaluation::RSpec 或 RubyLLM::Evaluation::Minitest 后，在 RSpec 或 Minitest 中使用 evaluates SupportEvaluation。每次运行的模型评分都会产生费用，因此除非应用会记录请求，否则不要将需要评分的评估纳入默认测试运行。

验证应用变更

运行与应用相关的测试。根据变更所涉及的内容，测试工具的业务行为、结构化解析、持久化对话的重建以及作业恢复。必要时，使用应用现有的录制或集成测试配置来验证模型调用；说明实际测试了哪种提供商行为。实现应限于所请求的功能，并遵循现有的应用架构。