openai Embedding

Zilla runtime openai embedding resolves text to a vector using OpenAI's embeddings API. It backs semantic tool search (binding-mcp-ext) or any other consumer of the embedding engine SPI with a hosted, managed embedding model.

Available in Zilla Plus

embedding:
  type: openai
  options:
    model: text-embedding-3-small
    credentials:
      api-key: ${{env.OPENAI_API_KEY}}

The embeddings endpoint URL is a JVM-wide zilla.embedding.openai.endpoint property (not a per-embedding YAML option), set via -P on the zilla start command line, so it can target any server implementing the same /v1/embeddings request/response shape, such as a self-hosted OpenAI-compatible server (vLLM, LiteLLM proxy, LocalAI):

zilla start -P zilla.embedding.openai.endpoint=http://localhost:8000/v1/embeddings

Configuration (* required)

zilla.embedding.openai.endpoint

string | Default: https://api.openai.com/v1/embeddings

Overrides the embeddings endpoint URL. Useful for OpenAI-compatible self-hosted servers that implement the same request/response schema, or for tests. Set as a JVM-wide property (-P on the CLI, or a zilla.properties file) — see zilla-cli — rather than in options, since it is typically fixed for the whole deployment rather than varying per embedding instance.

options

object

The openai specific options.

options.model *

string

The OpenAI embedding model id, e.g. text-embedding-3-small or text-embedding-3-large.

options.credentials *

object

The OpenAI credentials.

options.credentials.api-key *

string

The OpenAI API key, sent as an Authorization: Bearer header on each request. Typically supplied via an environment variable reference, e.g. ${{env.OPENAI_API_KEY}}, rather than inlined directly.

Note

The key needs only one restricted permission: Model capabilities > Embeddings (/v1/embeddings): Request. No other scopes are required.