Anthropic Ruby 函式庫讓任何 Ruby 3.2.0+ 應用程式都能方便地存取 Anthropic REST API。它隨附完整的型別以及 Yard、RBS 和 RBI 格式的文件字串(docstrings)。HTTP 傳輸使用標準函式庫的 net/http,並透過 connection_pool gem 提供連線池(connection pooling)功能。
如需包含程式碼範例的 API 功能文件,請參閱 API 參考。本頁面涵蓋 Ruby 特有的 SDK 功能與設定。
使用 Bundler 將 gem 加入您應用程式的 Gemfile:
bundle add anthropicRuby 3.2.0 或更高版本。
anthropic = Anthropic::Client.new(
api_key: ENV["ANTHROPIC_API_KEY"] # This is the default and can be omitted
)
message = anthropic.messages.create(
max_tokens: 1024,
messages: [{role: "user", content: "Hello, Claude"}],
model: :"claude-opus-5"
)
message.content.each do |block|
puts block.text if block.type == :text
end如需了解包含「Workload Identity Federation」(工作負載身分聯合)在內的驗證選項,請參閱驗證。
SDK 支援使用「Server-Sent Events」(伺服器推送事件),即 SSE,進行串流回應。
anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
max_tokens: 1024,
messages: [{role: "user", content: "Hello, Claude"}],
model: :"claude-opus-5"
)
stream.each do |message|
puts(message.type)
end此函式庫為串流訊息提供了多種便利功能,例如:
anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
max_tokens: 1024,
messages: [{role: :user, content: "Say hello there!"}],
model: :"claude-opus-5"
)
stream.text.each do |text|
print(text)
end使用 anthropic.messages.stream(...) 進行串流會提供各種輔助工具,包括累積(accumulation)功能和 SDK 特有的事件。
SDK 提供輔助機制來為工具定義結構化資料類別,並讓 Claude 自動執行它們。如需工具使用模式(包括工具執行器)的詳細文件,請參閱工具執行器(SDK)。
anthropic = Anthropic::Client.new
class CalculatorInput < Anthropic::BaseModel
required :lhs, Float
required :rhs, Float
required :operator, Anthropic::InputSchema::EnumOf[:+, :-, :*, :/]
end
class Calculator < Anthropic::BaseTool
input_schema CalculatorInput
def call(expr)
expr.lhs.public_send(expr.operator, expr.rhs)
end
end
# 自動處理工具執行迴圈
anthropic.beta.messages.tool_runner(
model: "claude-opus-5",
max_tokens: 1024,
messages: [{role: "user", content: "What's 15 * 7?"}],
tools: [Calculator.new]
).each_message { |message| puts message.content }如需包含 Ruby 範例的完整結構化輸出文件,請參閱結構化輸出。
當函式庫無法連線到 API,或 API 回傳非成功狀態碼(即 4xx 或 5xx 回應)時,會引發 Anthropic::Errors::APIError 的子類別:
anthropic = Anthropic::Client.new
begin
message = anthropic.messages.create(
max_tokens: 1024,
messages: [{role: "user", content: "Hello, Claude"}],
model: :"claude-opus-5"
)
rescue Anthropic::Errors::APIConnectionError => e
puts("The server could not be reached")
puts(e.cause) # an underlying Exception, likely raised within `net/http`
rescue Anthropic::Errors::RateLimitError => e
puts("A 429 status code was received; we should back off a bit.")
rescue Anthropic::Errors::APIStatusError => e
puts("Another non-200-range status code was received")
puts(e.status)
end錯誤代碼如下:
| 原因 | 錯誤類型 |
|---|---|
| HTTP 400 | BadRequestError |
| HTTP 401 | AuthenticationError |
| HTTP 403 | PermissionDeniedError |
| HTTP 404 | NotFoundError |
| HTTP 409 | ConflictError |
| HTTP 422 | UnprocessableEntityError |
| HTTP 429 | RateLimitError |
| HTTP >= 500 | InternalServerError |
| 其他 HTTP 錯誤 | APIStatusError |
| 逾時 | APITimeoutError |
| 網路錯誤 | APIConnectionError |
某些錯誤預設會自動重試 2 次,並採用短暫的指數退避(exponential backoff)。
連線錯誤(例如因網路連線問題)、408 Request Timeout、409 Conflict、429 Rate Limit、>=500 內部錯誤以及逾時,預設都會重試。
您可以使用 max_retries 選項來設定或停用此功能:
# 設定所有請求的預設值:
anthropic = Anthropic::Client.new(
max_retries: 0 # default is 2
)
# 或者,針對個別請求進行設定:
anthropic.messages.create(
max_tokens: 1024,
messages: [{role: "user", content: "Hello, Claude"}],
model: :"claude-opus-5",
request_options: {max_retries: 5}
)預設情況下,請求會在 10 分鐘後逾時。您可以使用 timeout 選項來設定:
# 設定所有請求的預設值:
anthropic = Anthropic::Client.new(
timeout: 20 # 20 seconds (default is 10 minutes)
)
# 或者,針對個別請求進行設定:
anthropic.messages.create(
max_tokens: 1024,
messages: [{role: "user", content: "Hello, Claude"}],
model: :"claude-opus-5",
request_options: {timeout: 5}
)逾時時會引發 Anthropic::Errors::APITimeoutError。
請注意,逾時的請求預設會重試。
Claude API 中的列表方法是分頁的。
此函式庫為每個列表回應提供自動分頁的迭代器,因此您不必手動請求後續頁面:
anthropic = Anthropic::Client.new
page = anthropic.messages.batches.list(limit: 20)
# 從頁面擷取單一項目。
batch = page.data[0]
puts(batch.id)
# 視需要自動擷取更多頁面。
page.auto_paging_each do |batch|
puts(batch.id)
end或者,您可以使用 #next_page? 和 #next_page 方法,以更精細的方式控制頁面的處理。
anthropic = Anthropic::Client.new
page = anthropic.messages.batches.list(limit: 20)
loop do
page.data&.each { |batch| puts(batch.id) }
break unless page.next_page?
page = page.next_page
end對應於檔案上傳的請求參數可以以原始內容、Pathname 實例、StringIO 等形式傳遞。
anthropic = Anthropic::Client.new
require "pathname"
# 使用 `Pathname` 來傳送檔案名稱,並/或避免將大型檔案分頁載入記憶體:
file_metadata = anthropic.beta.files.upload(file: Pathname("/path/to/file"))
# 或者,直接傳入檔案內容或 `StringIO`:
file_metadata = anthropic.beta.files.upload(file: File.read("/path/to/file"))
# 或者,若要控制檔案名稱和/或內容類型:
file = Anthropic::FilePart.new(File.read("/path/to/file"), filename: "/path/to/file", content_type: "...")
file_metadata = anthropic.beta.files.upload(file: file)
puts(file_metadata.id)請注意,您也可以傳遞原始的 IO 描述符,但這會停用重試功能,因為函式庫無法確定該描述符是檔案還是管道(管道無法倒回)。
此函式庫提供完整的 RBI 定義,且不依賴 sorbet-runtime。
您可以像這樣提供型別安全的請求參數:
anthropic = Anthropic::Client.new
anthropic.messages.create(
max_tokens: 1024,
messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
model: :"claude-opus-5"
)或者,等效地:
anthropic = Anthropic::Client.new
# Hash 可以運作,但不具型別安全:
anthropic.messages.create(
max_tokens: 1024,
messages: [{role: "user", content: "Hello, Claude"}],
model: :"claude-opus-5"
)
# 您也可以展開(splat)完整的 Params 類別:
params = Anthropic::MessageCreateParams.new(
max_tokens: 1024,
messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
model: :"claude-opus-5"
)
anthropic.messages.create(**params)由於此函式庫不依賴 sorbet-runtime,因此無法提供 T::Enum 實例。取而代之,SDK 提供「標記符號」(tagged symbols),在執行時期始終是原始型別:
# :auto
puts(Anthropic::MessageCreateParams::ServiceTier::AUTO)
# 揭示的型別:`T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)列舉參數具有「寬鬆」的型別,因此您可以傳入列舉常數或其字面值:
# 使用列舉常數可保留標記型別資訊:
anthropic.messages.create(
service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
# ...
)
# 也可以使用字面值:
anthropic.messages.create(
service_tier: :auto,
# ...
)所有參數和回應物件都繼承自 Anthropic::Internal::Type::BaseModel,它提供了多種便利功能,包括:
所有欄位(包括未知欄位)都可以使用 obj[:prop] 語法存取,並且可以使用 obj => {prop: prop} 或模式比對(pattern-matching)語法進行解構。
以結構等價性判斷相等;如果兩個 API 呼叫回傳相同的值,使用 == 比較回應將回傳 true。
實例和類別本身都可以進行美化列印(pretty-printed)。
輔助方法,例如 #to_h、#deep_to_h、#to_json 和 #to_yaml。
Anthropic::Client 實例是執行緒安全的(threadsafe),但只有在沒有進行中的 HTTP 請求時才是 fork 安全的。
每個 Anthropic::Client 實例都有自己的 HTTP 連線池,預設大小為 99。因此,在大多數情況下,建議每個應用程式只建立一次客戶端。
當連線池中所有可用的連線都被取用時,請求會等待新的連線變為可用,而排隊時間會計入請求逾時。
除非另有說明,SDK 中的其他類別沒有保護其底層資料結構的鎖。
您可以向任何端點發送未記載的參數,並讀取未記載的回應屬性,如下所示:
同名的 extra_ 參數會覆寫已記載的參數。基於安全考量,請確保這些方法僅用於可信任的輸入資料。
anthropic = Anthropic::Client.new
value = "example"
message =
anthropic.messages.create(
max_tokens: 1024,
messages: [{role: "user", content: "Hello, Claude"}],
model: :"claude-opus-5",
request_options: {
extra_query: {my_query_parameter: value},
extra_body: {my_body_parameter: value},
extra_headers: {"my-header": value}
}
)
puts(message[:my_undocumented_property])如果您想明確發送額外的參數,可以在發送請求時於 request_options: 參數下使用 extra_query、extra_body 和 extra_headers,如上面的範例所示。
若要在保留驗證、重試等優點的同時向未記載的端點發送請求,您可以使用 anthropic.request 發送請求,如下所示:
response = anthropic.request(
method: :post,
path: '/undocumented/endpoint',
query: {"dog": "woof"},
headers: {"useful-header": "interesting-value"},
body: {"hello": "world"}
)如需包含程式碼範例的詳細平台設定指南,請參閱:
Ruby SDK 支援以下平台:
Anthropic::VertexClient。需要 googleauth gem。Anthropic::BedrockMantleClient,或用於 bedrock-runtime 路徑的 Anthropic::BedrockClient。Anthropic::BedrockMantleClient 需要 aws-sdk-core gem;Anthropic::BedrockClient 需要 aws-sdk-bedrockruntime gem。anthropic gem 的一部分(需要 aws-sdk-core gem)。提供 Anthropic::AWSClient。將 workspace_id: 傳遞給建構函式,或設定 ANTHROPIC_AWS_WORKSPACE_ID 環境變數(請參閱工作區)。以測試版提供。新專案請使用 Anthropic::BedrockMantleClient;Anthropic::BedrockClient 保留給使用 Bedrock InvokeModel API 的現有應用程式。
此套件遵循 SemVer 慣例。由於此函式庫處於初始開發階段且主版本號為 0,API 可能隨時變更。
此套件將(非執行時期的)*.rbi 和 *.rbs 型別定義的改進視為非破壞性變更。
Was this page helpful?