repository·main·Indexed 25 days ago
https://github.com/alexrudall/ruby-openaiA Ruby client library for interacting with the OpenAI API. It supports GPT-5 streaming via the Responses API, Realtime WebRTC conversations, chat completions, embeddings, and asynchronous batches. The library also provides compatibility with Azure OpenAI Service and other OpenAI-compatible APIs such as Deepseek, Ollama, Groq, and Gemini.
For a quick test, you can instantiate a new client by passing your access_token directly. It is highly recommended to set log_errors: true during development to see the specific error responses returned by OpenAI, though this should be disabled in production to prevent leaking private data into logs.
client = OpenAI::Client.new(
access_token: "access_token_goes_here",
log_errors: true
)Assistants are stateful actors that can use tools like code_interpreter and file_search. You can create an assistant with specific instructions, tools, and tool resources (like vector stores or uploaded files).
response = client.assistants.create(
parameters: {
model: "gpt-4o",
name: "OpenAI-Ruby test assistant",
instructions: "You are a Ruby dev bot.",
tools: [{ type: "code_interpreter" }, { type: "file_search" }],
tool_resources: {
file_search: { vector_store_ids: ["vs_123"] }
}
}
)
assistant_id = response["id"]Upgrading to version 5.x changes how the client is configured and how audio methods are accessed:
OpenAI::Client instance now maintains its own configuration, which allows for multi-tenant usage.audio namespace. Use client.audio.translate and client.audio.transcribe instead of calling them directly on the client.The Conversations API allows you to create and manage persistent conversation states. You can create conversations, retrieve them, modify metadata, and manage individual items (messages) within a conversation.
# Create a conversation
response = client.conversations.create(
parameters: { metadata: { purpose: "customer_support" } }
)
conversation_id = response["id"]
# Add items (messages) to a conversation
client.conversations.create_items(
conversation_id: conversation_id,
parameters: {
items: [
{ type: "message", role: "user", content: [{ type: "input_text", text: "Hello!" }] }
]
}
)
# List items in a conversation
response = client.conversations.list_items(
conversation_id: conversation_id,
parameters: { limit: 10, order: "asc" }
)bin/setup to install dependencies. You can use bin/console to launch an interactive prompt for experimenting with the library. To install the gem locally from the source, use bundle exec rake install.bin/setup
bundle exec rake installUpgrading to version 6.x introduces the following breaking changes:
Faraday::Error, including during streaming operations.Upgrading to version 7.x involves API coverage changes and endpoint removals:
edits endpoint has been removed./v1/ to the configured base_uri if it is already present.The gem supports other providers that are compatible with the OpenAI API by changing the uri_base and access_token.
Deepseek
client = OpenAI::Client.new(
access_token: "deepseek_access_token_goes_here",
uri_base: "https://api.deepseek.com/"
)Ollama (Local)
client = OpenAI::Client.new(
uri_base: "http://localhost:11434"
)Groq
client = OpenAI::Client.new(
access_token: "groq_access_token_goes_here",
uri_base: "https://api.groq.com/openai"
)Gemini
client = OpenAI::Client.new(
access_token: "gemini_access_token_goes_here",
uri_base: "https://generativelanguage.googleapis.com/v1beta/openai/"
)For robust applications, use OpenAI.configure to set global defaults. This is typically done in an initializer file. Use environment variables (e.g., via dotenv) to avoid hardcoding secrets.
Available configuration keys:
access_token: Your OpenAI API key.admin_token: Optional, used for admin endpoints.organization_id: Optional, your OpenAI Organization ID.log_errors: Boolean to enable/disable error logging.uri_base: The base URI for all requests (useful for proxies or observability tools).request_timeout: Integer representing timeout in seconds (default is 120).extra_headers: A Hash of arbitrary headers to include in every request.OpenAI.configure do |config|
config.access_token = ENV.fetch("OPENAI_ACCESS_TOKEN")
config.admin_token = ENV.fetch("OPENAI_ADMIN_TOKEN") # Optional
config.organization_id = ENV.fetch("OPENAI_ORGANIZATION_ID") # Optional
config.log_errors = true
config.uri_base = "https://oai.hconeai.com/"
config.request_timeout = 240
config.extra_headers = {
"X-Proxy-TTL" => "43200",
"Helicone-Auth" => "Bearer HELICONE_API_KEY"
}
endIf you encounter issues with Ruby OpenAI, use the following channels:
Vector Stores enable the file_search tool by allowing you to group files into searchable collections. You can create stores, attach files (individually or in batches), search for relevant chunks using a query, and modify or delete them.
# Create a vector store
response = client.vector_stores.create(
parameters: {
name: "my vector store",
file_ids: ["file-abc123", "file-def456"]
}
)
vector_store_id = response["id"]
# Search the vector store
response = client.vector_stores.search(
id: vector_store_id,
parameters: {
query: "What is the return policy?",
max_num_results: 20,
rewrite_query: true
}
)To fine-tune a model, first upload your .jsonl training data to get a file_id. Then, use client.finetunes.create to start the job. You can monitor the job, cancel it if necessary, or retrieve the resulting fine-tuned model name to use in chat completions.
# 1. Upload training file
response = client.files.upload(parameters: { file: "path/to/sarcasm.jsonl", purpose: "fine-tune" })
file_id = JSON.parse(response.body)["id"]
# 2. Create fine-tune job
response = client.finetunes.create(
parameters: {
training_file: file_id,
model: "gpt-4o"
}
)
fine_tune_id = response["id"]
# 3. Retrieve the fine-tuned model name once processed
response = client.finetunes.retrieve(id: fine_tune_id)
fine_tuned_model = response["fine_tuned_model"]
# 4. Use the new model in chat
response = client.chat(
parameters: {
model: fine_tuned_model,
messages: [{ role: "user", content: "I love Mondays!" }]
}
)