Apple Foundation Models

Claude for Foundation Models adalah paket Swift yang membuat Claude tersedia sebagai model bahasa sisi server dalam framework Foundation Models dari Apple. Paket ini membuat Claude sesuai dengan protokol LanguageModel dari framework tersebut, sehingga Anda menggunakannya dengan API LanguageModelSession yang sama seperti yang Anda gunakan untuk model on-device Apple: respond(to:), streaming, guided generation, dan pemanggilan alat semuanya bekerja dengan cara yang sama.

Permintaan dikirim langsung dari aplikasi Anda ke Claude API; Apple tidak berada dalam jalur permintaan dan tidak melihat prompt atau respons. Penggunaan ditagihkan ke akun Anthropic Anda dengan harga API standar. Aplikasi Anda yang memutuskan kapan menggunakan Claude dan kapan menggunakan model on-device Apple: berikan model mana pun yang Anda inginkan ke setiap sesi.



Persyaratan

• iOS 27, macOS 27, visionOS 27, atau watchOS 27 (semuanya dalam beta): rilis OS yang framework Foundation Models-nya mendukung model bahasa sisi server
• Xcode 27 (beta)
• Kunci API Claude dari Claude Console untuk pengembangan. Lihat Autentikasi untuk opsi produksi.



Instal paket

Tambahkan paket ke Package.swift Anda:

dependencies: [
  .package(url: "https://github.com/anthropics/ClaudeForFoundationModels.git", from: "0.1.0")
]

Atau di Xcode: File > Add Package Dependencies… dan masukkan URL repositori.

Kemudian tambahkan ClaudeForFoundationModels ke dependensi target Anda dan impor bersama FoundationModels:

import FoundationModels
import ClaudeForFoundationModels



Mulai cepat

ClaudeLanguageModel adalah titik masuknya. Berikan ke LanguageModelSession dan gunakan sesi tersebut persis seperti yang Anda lakukan dengan penyedia Foundation Models mana pun:

import FoundationModels
import ClaudeForFoundationModels

let model = ClaudeLanguageModel(
  name: .sonnet5,
  auth: .apiKey(ProcessInfo.processInfo.environment["ANTHROPIC_API_KEY"] ?? "")
)

let session = LanguageModelSession(model: model)
let response = try await session.respond(to: "Plan a 4-day trip to Buenos Aires.")
print(response.content)

Initializer juga menerima baseURL (default https://api.anthropic.com), timeout, dan serverTools (lihat Alat sisi server).

Untuk program lengkap yang berfungsi, repositori menyertakan Examples/ClaudeExample, target command-line yang dapat dijalankan yang melakukan streaming giliran obrolan ke terminal, dengan flag --search yang mengaktifkan pencarian web sisi server untuk giliran tersebut. Menjalankannya memerlukan host macOS 27.



Memilih model

Pengidentifikasi model adalah nilai dari ClaudeModel. Gunakan konstanta yang sudah dikompilasi, atau buat satu dengan kapabilitas eksplisit untuk ID yang belum dikompilasi (lihat Kapabilitas):

ClaudeLanguageModel(name: .opus5, auth: auth)

Konstanta mencerminkan ID model API (.opus5 adalah claude-opus-5) dan membawa kapabilitas setiap model. Model baru hadir sebagai konstanta baru dalam rilis paket; periksa ClaudeModel di Xcode untuk daftar terkini, dan Ikhtisar model untuk membandingkan model.



Kapabilitas

Setiap ClaudeModel mendeklarasikan apa yang diterimanya: parameter sampling, tingkat effort, adaptive thinking, structured output, dan input gambar. Paket menggunakan ini untuk menentukan field permintaan mana yang akan dikirim, karena mengirim field yang ditolak model adalah kesalahan fatal. Konstanta membawa kapabilitas yang tepat. Untuk ID yang belum dikompilasi, deklarasikan apa yang diterima model (sengaja tidak ada cara singkat yang menebak):

let model = ClaudeModel(
  id: "claude-experimental-x",
  capabilities: .init(samplingParams: false, effortLevels: [.low, .high])
)
ClaudeLanguageModel(name: model, auth: auth)



Effort

Tetapkan tingkat effort Claude untuk setiap permintaan dengan fixedEffort:. Ini lebih diutamakan daripada petunjuk reasoning per-permintaan dari framework. Tingkat reasoning bernama dari framework berhenti di high; untuk meminta effort lebih tinggi untuk satu permintaan saja, berikan tingkat reasoning kustom yang menamai effort Claude (.custom("xhigh") atau .custom("max")), yang dipetakan secara langsung. API secara default menggunakan high ketika tidak ada effort yang dikirim:

ClaudeLanguageModel(name: .opus5, auth: auth, fixedEffort: .xhigh)

Tingkat tersebut harus yang diterima oleh model. Setiap ClaudeModel mendeklarasikan mana dari lima tingkat (low, medium, high, xhigh, max) yang diterima modelnya, jika ada: beberapa model tidak menerima effort sama sekali.



Kapan menggunakan Claude versus model on-device

Model on-device Apple cepat, privat, dan tersedia secara offline, tetapi ukurannya dirancang untuk tugas ringan. Eskalasikan ke Claude ketika Anda memerlukan konteks yang lebih besar, reasoning tingkat frontier, atau alat sisi server seperti pencarian web dan eksekusi kode. Karena keduanya menggunakan API LanguageModelSession yang sama, Anda dapat beralih dengan menukar argumen model:.



Autentikasi

Atur kredensial dengan parameter auth:.



Kunci API (pengembangan)

Berikan kunci API secara langsung saat mengembangkan:

ClaudeLanguageModel(name: .sonnet5, auth: .apiKey("YOUR_API_KEY"))



Proxy (produksi)

Untuk produksi, arahkan permintaan melalui back end Anda sendiri dengan .proxied. Relay di baseURL menambahkan kredensial Claude API di sisi server, sehingga aplikasi tidak menyertakan kunci. headers yang Anda berikan dikirim pada setiap permintaan sehingga proxy Anda dapat mengotorisasi pemanggil. Berikan [:] jika tidak memerlukan apa pun:

ClaudeLanguageModel(
  name: .sonnet5,
  auth: .proxied(headers: ["X-App-Token": "..."]),
  baseURL: URL(string: "https://api.yourapp.com/claude")!
)

Proxy Anda menerima permintaan Messages API standar, melampirkan header x-api-key, dan meneruskannya ke https://api.anthropic.com.



Streaming

streamResponse(to:) mengembalikan respons secara bertahap. Setiap elemen adalah snapshot kumulatif dari respons sejauh ini, bukan delta:

let stream = session.streamResponse(to: "Summarize today's top science stories.")
for try await partial in stream {
  print(partial.content)
}



Structured output

Anotasikan sebuah tipe dengan @Generable dan minta dengan generating:. Model mengembalikan nilai dari tipe tersebut melalui structured outputs:

@Generable
struct Trip {
  @Guide(description: "Destination city") var destination: String
  @Guide(description: "Length in days") var days: Int
}

let response = try await session.respond(to: "Plan a trip to Tokyo.", generating: Trip.self)
print(response.content.destination)

Structured output memerlukan model yang kapabilitasnya mencakup fitur tersebut (semua konstanta yang sudah dikompilasi mendukungnya). Jika model yang dipilih tidak mendukung, paket akan melempar LanguageModelError.unsupportedGenerationGuide alih-alih menurunkan kualitas secara diam-diam.



Penggunaan alat



Alat sisi klien

Array tools: dari framework bekerja tanpa perubahan. Buat tipe Anda sesuai dengan Tool, berikan ke LanguageModelSession, dan framework akan memanggilnya di perangkat ketika Claude memanggilnya. Lihat Penggunaan alat dengan Claude.

let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()])



Alat sisi server

Server tools (pencarian web, pengambilan web, dan eksekusi kode) berjalan di infrastruktur Anthropic dalam satu round trip, tanpa ada yang perlu dipanggil framework di perangkat. Konfigurasikan untuk setiap model dengan serverTools::

let model = ClaudeLanguageModel(
  name: .sonnet5,
  auth: auth,
  serverTools: [
    .webSearch(maxUses: 5),
    .codeExecution,
  ]
)

.webSearch dan .webFetch menerima allowedDomains, blockedDomains, dan maxUses opsional. Aktivitas alat server muncul dalam transkrip sebagai segmen kustom ClaudeServerToolSegment.



Gambar

Model yang kapabilitasnya mencakup input gambar mendeklarasikan kapabilitas vision dari framework. Berikan konten gambar melalui API sesi standar framework; paket mengonversinya ke format gambar Claude API. Lihat Vision untuk persyaratan gambar.



Penanganan kesalahan

Paket memetakan kesalahan Claude API ke case LanguageModelError dari Apple jika ada yang sesuai: overflow jendela konteks muncul sebagai .contextSizeExceeded, HTTP 429 sebagai .rateLimited, permintaan yang melewati timeout yang dikonfigurasi sebagai .timeout. Kesalahan penyedia yang tidak memiliki padanan di framework muncul sebagai ClaudeError. Gunakan pattern-matching untuk mengarahkan alur produk:

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Meminta kunci API.
} catch let error as LanguageModelError {
  // Error terkait framework (batas laju, guardrail, panjang konteks, decoding).
} catch {
  // Error transport.
}

Pola yang umum adalah menangkap .rateLimited dan beralih ke SystemLanguageModel untuk giliran tersebut, mengantrekan permintaan, atau menampilkan opsi coba lagi.



Dukungan fitur

Paket menampilkan kapabilitas Messages API yang dapat diekspresikan oleh protokol penyedia Foundation Models. Fitur yang tidak memiliki representasi dalam protokol Apple tidak tersedia melaluinya, termasuk:

• Kontrol caching prompt (paket menerapkan caching prompt secara otomatis; TTL cache dan penempatan breakpoint tidak dapat dikonfigurasi)
• Stop sequences
• Pemrosesan batch
• Files API
• Penghitungan token
• Header beta



Sumber daya tambahan

Paket ini dilisensikan di bawah Apache 2.0. Laporan bug diterima melalui GitHub issues. Pull request eksternal tidak diterima selama periode beta.