feat(embedding): support dimensions for openai-compatible Matryoshka models (#405)

Closed
GU
1mo ago
+40-1

Fixes #405

Summary

Add optional embedding.dimensions for the openai-compatible provider to support Matryoshka models like Qwen3-Embedding-8B (768/1024/2048/4096 via POST {dimensions}).

Omitted keeps current behavior (byte-identical identity, no re-embed). Setting triggers per-model coexistence re-embed.

Changes

  • Schema packages/plugin/src/config/schema/magic-context.ts: BaseEmbeddingConfigSchema.dimensions (max 8192) + include in EmbeddingConfigSchema.transform for openai-compatible/synapse
  • Identity embedding-identity.ts: getEmbeddingProviderIdentity folds ...dimensions?{dimensions}:{}
  • Runtime embedding.ts / project-embedding-registry.ts: resolveEmbeddingConfig preserves dimensions; getChunkEmbeddingModelId includes dimensions; EMBEDDING_AFFECTING_KEYS adds embedding.dimensions
  • Transport embedding-openai.ts: OpenAICompatibleEmbeddingProviderOptions.dimensions, this.dimensions, modelId includes dimensions, embedBatch adds ...this.dimensions?{dimensions}:{} to POST /v1/embeddings
  • Schema JSON assets/magic-context.schema.json regenerated via bun build-schema.ts pattern (manual edit matching generator output)

Mirrors existing truncate/input_type/local_dtype conditional-fold pattern (#127, #155, #259).

Testing

  • Local pi-magic-context@0.41.1 (Pi 0.84.4) with Qwen3-Embedding-8B via openai-compatible:
    • no dimensions → 768 (en) / 1024 (zh) dims
    • dimensions:4096 → 16384 bytes / 4096 dims (memory 2 → 0f395...), verified via memory_embeddings and embedding_registrations
    • doctor passes; build-schema guard would pass after regeneration

Checklist

  • Follows truncate fold pattern (conditional spread, no global re-embed when omitted)
  • Updates EMBEDDING_AFFECTING_KEYS for untrusted-load GC guard
  • Regenerates assets/magic-context.schema.json

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

Summary by cubic

Fixes #405 by adding optional embedding.dimensions for the openai-compatible provider so Matryoshka models like Qwen3-Embedding-8B can be pinned to 768/1024/2048/4096. Omitting it keeps the current byte-identical identity; setting it sends dimensions in the POST /v1/embeddings body and folds it into the chunk identity, so changing it re-embeds existing vectors. The synapse fallback also carries dimensions so fallback requests and identities use the configured value instead of the provider default.

  • Validates dimensions in the config schema with a max of 8192.
  • Adds embedding.dimensions to EMBEDDING_AFFECTING_KEYS so config changes trip the GC guard on untrusted loads.
  • Regenerates assets/magic-context.schema.json.

Greptile Summary

The PR adds configurable output dimensions for OpenAI-compatible Matryoshka embedding models while preserving the existing provider-default behavior when omitted.

  • Adds schema validation and generated JSON Schema coverage for embedding.dimensions.
  • Includes configured dimensions in embedding identities so vector widths can coexist safely.
  • Propagates dimensions through direct and Synapse fallback routing into OpenAI-compatible embedding requests.
  • Treats dimensions as embedding-affecting configuration for registry and garbage-collection safeguards.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed
FilenameOverview
packages/plugin/src/config/schema/magic-context.tsAdds bounded positive-integer validation and preserves dimensions for OpenAI-compatible and Synapse configurations.
packages/plugin/src/plugin/embedding-routing.tsCompletes the prior fix by carrying Synapse dimensions into OpenAI-compatible fallback configurations.
packages/plugin/src/features/magic-context/memory/embedding-openai.tsNormalizes dimensions, includes them in provider identity, and sends them in embedding requests.
packages/plugin/src/features/magic-context/memory/embedding-identity.tsIncorporates explicitly configured dimensions into OpenAI-compatible provider identities.
packages/plugin/src/features/magic-context/project-embedding-registry.tsPreserves dimensions during registry resolution and includes them in chunk-model identity.
packages/plugin/src/plugin/embedding-bootstrap-helpers.tsMarks dimensions as embedding-affecting configuration for guarded registry updates.
assets/magic-context.schema.jsonPublishes the new optional dimensions field with the same validation constraints as the source schema.

Flowchart

 
%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Config[Embedding configuration] --> Schema[Schema validation]
    Schema --> Routing{Provider routing}
    Routing -->|OpenAI-compatible| Resolve[Resolved embedding config]
    Routing -->|Synapse fallback| Fallback[OpenAI-compatible fallback config]
    Fallback --> Resolve
    Resolve --> Identity[Provider and chunk identities]
    Resolve --> Provider[OpenAI-compatible provider]
    Provider --> Request[POST /v1/embeddings with optional dimensions]

Reviews (2): Last reviewed commit: "fix(embedding): propagate dimensions thr..." | Re-trigger Greptile

Context used: