Embeddings

Use embed for a single text value and embedMany when you want one request to cover multiple inputs.

Examples/Sources/Embeddings/main.swift

import SwiftAISDK

@main
struct EmbeddingsExample {
    static func main() async throws {
        let provider = try AIProviders.openAI()
        let model = try provider.embeddingModel("text-embedding-3-small")

        let result = try await model.embed(
            "Swift makes API boundaries explicit.",
            dimensions: 512
        )

        print(result.embeddings.first ?? [])
    }
}

For batches, pass all values at once. The facade automatically honors the model’s advertised per-request count and UTF-8 byte limits while preserving result order. OpenAI and Azure embeddings, for example, advertise a 300,000-byte input budget. Use chunkSize to request smaller chunks; it cannot override a stricter provider maximum.

let result = try await model.embedMany(
    ["alpha", "beta", "gamma"],
    chunkSize: 100
)

for vector in result.embeddings {
    print(vector.count)
}

Count and byte limits are applied together in one pass. An individual value larger than the byte budget stays intact in its own request so the provider can return its native validation error instead of the SDK silently truncating it. Every provider response must also contain exactly one vector for each input in that request. A mismatch is rejected before the facade merges chunked results, preventing silently shifted input/vector associations.

Options

• dimensions requests a provider-supported embedding size.
• providerOptions carries provider-specific settings.
• extraBody is a low-level escape hatch for unsupported provider fields.
• headers, abortSignal, retryPolicy, and telemetry work the same way as other facade calls.

Results

EmbeddingResult includes normalized vectors plus request and response metadata:

• embeddings
• usage
• warnings
• providerMetadata
• requestMetadata
• responseMetadata