feat(semantic): OpenAI-compatible remote embedding adapter

[esengine]

Driven by discussion #310 — local Ollama on a CPU-only VM is too slow for first-time indexing, and pointing OLLAMA_URL at a remote box still requires running Ollama somewhere. A real third-party endpoint is the next step.

Why

Current state (src/index/semantic/embedding.ts):

• Hardcoded to Ollama's /api/embeddings shape.
• OLLAMA_URL env var supports a remote Ollama daemon but not non-Ollama providers.
• probeOllama similarly Ollama-specific.

Gemini, OpenAI, vLLM, llama.cpp's server, LM Studio, and most third-party providers all expose POST /v1/embeddings with the same request/response shape. One adapter covers them all.

Scope

One adapter, OpenAI-compatible. No per-vendor code paths.

• New env vars (or config keys):
  • REASONIX_EMBED_PROVIDER — ollama (default) | openai-compat
  • REASONIX_EMBED_BASE_URL — full base URL when provider is openai-compat (e.g. https://generativelanguage.googleapis.com/v1beta/openai, https://api.openai.com/v1, http://localhost:8000/v1)
  • REASONIX_EMBED_API_KEY — bearer token, sent as Authorization: Bearer <key>
  • REASONIX_EMBED_MODEL already exists — reused as the model name passed to the API
• Ollama remains the default. Zero behavior change for existing users.
• Adapter dispatch hidden behind the existing embed() / embedAll() / probe*() surface; callers see one API.

Constraints

• Vector dimensions per store. Different models output different dims (Ollama nomic-embed-text = 768, OpenAI text-embedding-3-small = 1536, Gemini text-embedding-004 = 768). The vector store must refuse mixing embeddings from different model identities — index header records { provider, model, dim } and rejects appends that don't match. Caller can rebuild the index when switching providers.
• No "free tier" framing in docs. Document that an OpenAI-compatible endpoint can be Gemini / OpenAI / etc., without promising free. Free tiers move on someone else's schedule.
• Errors stay actionable. ECONNREFUSED keeps Ollama install hint when provider is Ollama; OpenAI-compat path needs its own "check your API key / base URL" hint on 401 / 404.

Non-goals

• Per-vendor adapters (Gemini-specific, OpenAI-specific). One OpenAI-compat shape, period.
• Auto-migrating an existing Ollama-built index to a new provider. User rebuilds.
• Embedding-cache schema changes. Cache key already includes the model name; extending to include provider is straightforward but separable.

Acceptance

• REASONIX_EMBED_PROVIDER=openai-compat + REASONIX_EMBED_BASE_URL + REASONIX_EMBED_API_KEY produces a working embedder that can build an index via reasonix semantic build.
• Default behavior (no env vars set) is byte-identical to today.
• Vector store rejects appending vectors from a different { provider, model } than the index was built with.
• Test fixture: a fake OpenAI-compat endpoint (vitest vi.fn-driven fetch) drives the adapter through one happy-path embed and one 401 error.
• README / docs include one short paragraph on the env vars + a single example pointing at api.openai.com/v1 (no "free" framing).

[kabaka9527]

Can the custom request body feature be added to adapt to strict API services that require verification of parameters such as encoding_format?

[esengine]

A generic custom-body bag is something I want to avoid — it turns the adapter into a config dumping ground and pushes debugging back onto users.

Two narrower fixes that probably cover the real case:

1. Always send encoding_format: "float" in the request. We need float arrays anyway, and strict servers that reject the absence of the field will accept the explicit value.
2. If a specific provider needs a specific named param, I'll add it as a first-class option.

Which service did you hit, and what did it reject? That decides between (1) and (2).

[kabaka9527]

我想避免使用通用的定制车身包——它会把适配器变成配置倾倒场，调试工作又推回用户身上。

有两个更狭窄的解决方案，可能涵盖了真实情况：

1. 一定要提交申请。我们本来就需要浮点数组，而严格拒绝字段缺失的服务器会接受显式值。encoding_format: "float"
2. 如果某个特定提供者需要特定的命名参数，我会把它作为一流选项添加。

你打了哪个服务，它拒绝了什么？这决定了（1）和（2）之间的选择。

The API I use requires explicit values, "Embedding provider returned 400: {"errors":{"message":"encoding_format must be 'float' or 'base64', got ''"} " ,and in fact, this is a default value, but some APIs provide it as a normal float or base64. Users may have their own ideas to choose float & base64, while some APIs require explicitly specifying this value. Increasing custom requests can also achieve custom embedded dimension values in the API. The default values of the APIs chosen by users may not meet user needs

[esengine]

Both encoding_format and dimensions are named OpenAI params, so they fit option (2) — first-class options, not a generic body bag.

Plan for the adapter:

• encoding_format — exposed as a config option, defaulting to "float". We only support "float" on the read side initially (the parser decodes float arrays). "base64" can be added if a server actually rejects "float", but I'd rather not write the base64 decode path on speculation.
• dimensions — exposed as an optional config option, sent through when set. Vector store header records it alongside { provider, model, dim } so mismatched indexes still fail loudly.

No arbitrary pass-through. If a third param shows up, we name it.

[kabaka9527]

both 和 都被命名为 OpenAI 参数，因此它们符合选项 (2) — 一流选项，而不是一个通用的包体。encoding_format``dimensions

适配器计划：

• encoding_format — 作为配置选项暴露，默认为 。我们最初只在读取端支持（解析器解码浮点数数组）。如果服务器实际拒绝 ，可以添加，但我宁愿不基于猜测编写 base64 解码路径。"float"``"float"``"base64"``"float"
• dimensions — 作为可选配置选项暴露，设置时通过发送。向量存储头记录与一起发送，因此不匹配的索引仍然会大声失败。{ provider, model, dim }

不进行任意传递。如果出现第三个参数，我们会命名它。

Actually, users don't need to guess; the API should provide corresponding documentation. I will start implementing the custom request feature, using merge to add request bodies.

[esengine]

Pulling back on the no-bag stance — you're partly right. "OpenAI-compatible" is an open-shape ecosystem (Cohere input_type, Gemini task_type, vLLM truncate, etc.), and forcing every vendor quirk through a new release is the wrong friction. OpenAI's own SDK has extra_body for the same reason.

Updated plan:

• encoding_format?: "float" | "base64" — first-class typed option, default "float". The "base64" value requires the matching decode path on the read side; not optional.
• dimensions?: number — first-class option, sent when set, recorded in the vector-store header alongside { provider, model, dim }. This one can't go in the bag because mismatched dims silently corrupt indexes.
• extraBody?: Record<string, unknown> — escape hatch for vendor-specific fields, merged into the request body after the named params. Documented as user-supplied, not validated, server-specific behavior.

Merge order: named params override extraBody, so the bag can't accidentally clobber model / encoding_format / dimensions.

Happy to take the PR if you still want to write it.

[kabaka9527]

Pulling back on the no-bag stance — you're partly right. "OpenAI-compatible" is an open-shape ecosystem (Cohere , Gemini , vLLM , etc.), and forcing every vendor quirk through a new release is the wrong friction. OpenAI's own SDK has for the same reason.input_type``task_type``truncate``extra_body

Updated plan:

• encoding_format?: "float" | "base64" — first-class typed option, default . The value requires the matching decode path on the read side; not optional."float"``"base64"
• dimensions?: number — first-class option, sent when set, recorded in the vector-store header alongside . This one can't go in the bag because mismatched dims silently corrupt indexes.{ provider, model, dim }
• extraBody?: Record<string, unknown> — escape hatch for vendor-specific fields, merged into the request body after the named params. Documented as user-supplied, not validated, server-specific behavior.

Merge order: named params override , so the bag can't accidentally clobber / / .extraBody``model``encoding_format``dimensions

Happy to take the PR if you still want to write it.

Alright, I'll start implementing the features