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.

Custom embedding models can expose providerOptionsTransformer. When the facade splits an embedMany request, the transformer receives the full value list plus the current startIndex/endIndex range and returns options for that batch. The transformed options stay stable across retries of that batch, so parallel provider-option arrays remain aligned with their input values.

Options

• dimensions requests a provider-supported embedding size and must be positive. Validation runs before model work, even for an empty embedMany input. Alibaba, Bedrock, Cohere, Gateway, Google/Vertex, Mistral, compatible, Perplexity and Voyage adapters use it as the default; a documented provider-specific dimension overrides the shared value.
• 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