openai/openai-ruby

openai/openai‑ruby – OpenAI API 官方 Ruby 客户端

它是什么

• 一个封装 OpenAI REST API 的 Ruby gem，让 Ruby 3.3+ 应用程序可以调用 GPT‑4、Whisper、DALL‑E 以及更新的 Realtime 和 Agents 端点等模型。
• 提供类型化的请求/响应对象、Yard 文档、用于 Sorbet 的 RBS/RBI 文件，以及内置的分页、流式和文件上传辅助功能。

主要能力

• Chat 和补全 – 简单的 client.chat.completions.create 调用。
• 流式传输 – Server‑Sent Events (SSE) 用于增量 token 输出。
• Agents（测试版） – 创建长时间运行的代理会话，检索最终结构化结果，并下载生成的工件。
• Realtime WebSockets – 块范围文本、转写、语音和 WebRTC 通话控制。
• Responses WebSocket – 持久的多路复用响应创建。
• 文件处理 – 上传、处理轮询、为托管环境暂存文件、下载工件。
• 自定义 HTTP 传输 – 可插入您自己的客户端（例如用于连接池、mTLS 或特殊代理逻辑）。
• 提供商集成 – 支持 Azure OpenAI、Amazon Bedrock 和工作负载身份验证。

典型使用场景

• 在 Ruby Web 或后台服务中构建聊天机器人、助手或任何 LLM 驱动的功能。
• 直接从 Ruby 代码生成图像、音频或转写。
• 运行需要有状态交互和文件 I/O 的长时间运行的代理工作流。
• 使用 Realtime WebSocket API 的实时语音或文本应用。
• 在不更改代码的情况下集成 Azure OpenAI 或 AWS Bedrock。

安装

# 在 Gemfile 中
"gem "openai", "~> 0.103.0""

运行 bundle install。该 gem 适用于 Ruby 3.3 或更高版本。

快速开始

require "bundler/setup"
require "openai"

client = OpenAI::Client.new(api_key: ENV["OPENAI_API_KEY"]) # 如果设置了环境变量，key 可选

# 简单聊天补全
resp = client.chat.completions.create(
  model: "gpt-4o-mini",
  messages: [{role: "user", content: "Say this is a test"}]
)
puts resp

流式示例

stream = client.responses.stream(input: "Write a haiku about OpenAI.", model: "gpt-4o-mini")
stream.each { |event| puts event.type }

Agent（测试版）示例

stream = client.beta.agents.sessions.create_streaming(
  agent: {model: "gpt-4o-mini", instructions: "Summarize the policy clearly."},
  environment: {type: :none},
  input: "Explain this policy: ..."
)
result = stream.get_final_result
puts result.output_text

高级功能

• 使用 OpenAI::BaseModel 子类声明结构化输出类型并自动解析。
• 使用 client.files.create 上传本地文件，或使用 client.beta.agents.environments.files.prepare 为代理环境暂存。
• 通过构建带客户端证书的自定义 OpenAI::NetHTTPClient 并将其传递给 OpenAI::Client，启用互 TLS。
• 切换提供商：

  client = OpenAI::Client.new(provider: OpenAI::Providers.azure(endpoint: ENV["AZURE_OPENAI_ENDPOINT"], api_key: ENV["AZURE_OPENAI_API_KEY"]))
  

成熟度和支持

• 由 OpenAI（官方存储库）积极维护。
• RubyDoc 和 OpenAI 平台文档提供全面文档。
• 支持最新 OpenAI 功能（Agents、Realtime、向量存储等），并带有测试版标志。

许可证

• 根据 MIT 许可证分发（请参阅存储库的 LICENSE 文件）。

---

此摘要仅基于 openai/openai‑ruby 存储库的 README 内容。