OpenAI

Hosted embeddings through OpenAI's API. The key stays in providers.d on the inference host (the database machine in embedded mode, each postvec-server in remote mode).

1. Add the provider

sudo postvec provider add openai --model text-embedding-3-small
postvec provider ls
sudo postvec doctor --database app

In a container: docker exec -it postvec postvec provider add openai --model text-embedding-3-small.

The command prompts for the key without echo, writes /etc/postvec/providers.d/openai.toml (0600), probes the key with one embed call, reloads the host and refreshes postvec.models.

Expected

providers.d: /etc/postvec/providers.d
openai  (openai, key: inline (redacted))
  openai-text-embedding-3-small                dim 1536   served

doctor exits 0. The name is in postvec.models.

Built-in catalogue names:

--model	Name in SQL	Dim
text-embedding-3-small	openai-text-embedding-3-small	1536
text-embedding-3-large	openai-text-embedding-3-large	3072
text-embedding-ada-002	openai-text-embedding-ada-002	1536

Any other OpenAI embedding id works. The probe measures the dimension, or --dim states it with --no-verify. Repeat --model to add several in one file.

Pass --api-key-file PATH, --api-key-env OPENAI_API_KEY or --key-stdin instead of the prompt. With --api-key-file the key stays in that file and provider ls reports file:PATH instead of inline. --base-url fronts an OpenAI-compatible origin (Azure's /openai/v1 API is this shape).

2. Bind a column

SELECT postvec.enable('docs', 'body',
                      model => 'openai-text-embedding-3-small');
-- NOTICE:  postvec: model "openai-text-embedding-3-small" is served by
--          external provider "openai"; source text from column "body" will
--          be sent to that provider for embedding

INSERT INTO docs(body) VALUES ('quarterly revenue guidance increased');

SELECT relation, model, dim, pending_jobs, dead_jobs
  FROM postvec.status();

Expected

pending_jobs returns to 0. docs.body_semantic is vector(1536). dead_jobs is 0.

SET postvec.query_timeout_ms = 10000;

SELECT postvec.create_vector_index('docs', 'body');

SELECT * FROM postvec.search('docs', 'body', 'revenue outlook', limit_n => 5);

To keep an existing openai-text-embedding-ada-002 column and search it through a local converter, search a retired space. Adding this key later creates a direct OpenAI route for that name; provider add lists affected columns and asks first.

On postvec-server

Run the add on a postvec-server node. The CLI finds no local cluster there and writes <server-root>/providers.d, the directory that node serves from:

sudo postvec provider add openai --model text-embedding-3-small \
     --acknowledge-in-use --yes

Copy the same file onto every node, then reload each host. External providers covers keys, failures and moving a column off the provider.

• External providers
• Connector files
• postvec-server