Embeddings workflow

Turns text segments into vector embeddings. Writes to a storage provider (pgvector by default) so search endpoints can retrieve them.

Minimal pipeline

version: "1.0"

routes:
  embedding_generator:
    inbound:
      queue: "/queue/embeddings.input"
      subscription: "embedding-processors"
      concurrency: 3   # LLM rate limit likely dominant

    adapters:
      - type: "embedding_generator"
        config:
          provider: "default"
          model: "text-embedding-3-small"
          storage_providers:
            - type: "pgvector18"

Storage backends

Backend	Config type	Use
PostgreSQLStorageProvider	pgvector18	Production. Queryable via the server’s search endpoints.
MessagePackStorageProvider	messagepack	Local experimentation. No search server needed.

Both satisfy EmbeddingStorageProvider. Swap via config.

Multi-model

Bind a pipeline to multiple embedding slots (e.g., English + Norwegian):

- type: "embedding_generator"
  config:
    provider: "default"
    model: "text-embedding-3-large"
    storage_slots:
      - name: "en-large"
        provider: {type: "pgvector18"}
      - name: "no-large"
        provider: {type: "pgvector18"}

Queries via POST /api/v1/search/multi-model target specific slots or fan out.

Querying embeddings

Once written, search via the API (or CLI):

factflow search semantic "your question"
factflow search hybrid "exact term AND intent"
factflow search multi-model "cross-language query" --models en-large,no-large

See the chat & search guide for the full surface.

Batching

embedding_generator batches requests to the LLM provider for efficiency. Batch size is configurable; default respects provider-specific token limits.

Lineage records one row per input message (not per batch entry) with batch_id set — see the lineage guide for per-batch inspection.

Direct use

Outside a pipeline:

from factflow_embeddings import EmbeddingService, EmbeddingConfig

service = EmbeddingService(config=EmbeddingConfig(...))
vectors = await service.embed(["text one", "text two"])

Related

• factflow-embeddings reference
• factflow-llm reference — embedding clients
• Markdown workflow — typical upstream segmenter
• Chat and search guide — how embeddings surface to end users