embeddings — Vector embedding adapters for retrieval & semantic search

Vector embedding adapters for retrieval & semantic search

Module langchain_classic/embeddings/ — Vector embedding adapters for retrieval & semantic search. Part of the Models I/O group.

🎯 Why This Module Exists

Embedding models map text to fixed-dimension vectors. The Embeddings ABC has just two methods — embed_documents(texts) and embed_query(text) — which deliberately keeps the contract minimal so any vector store, retriever, or compression filter can compose with any embedding provider.

Source files

Sub-directories

Models I/O

Architecture

flowchart LR
  subgraph Core["langchain_classic/embeddings/"]
    BASE["Base abstraction"]
    IMPLS["Concrete implementations"]
    BASE --> IMPLS
  end
  subgraph Up["Upstream callers"]
    U1["chains/"]
    U2["agents/"]
  end
  subgraph Down["Downstream"]
    D1["langchain_core"]
    D2["External providers"]
  end
  Up --> Core
  Core --> Down

Data Flow

sequenceDiagram
  participant Caller as Caller
  participant Embeddin as embeddings
  participant Core as langchain_core
  participant Ext as External
  Caller->>Embeddin: invoke(input)
  Note over Embeddin: Validate & route
  Embeddin->>Core: delegate primitive
  Core->>Ext: provider call
  Ext-->>Core: response
  Core-->>Embeddin: typed output
  Embeddin-->>Caller: result

Design Decisions

Decision	Choice Made	Alternatives	Why This Approach
Two methods (docs vs query)	Separate, possibly with different prompts	One method	Some providers (Instructor, BGE) use different prefixes for queries vs documents
Synchronous default + async opt-in	embed_documents sync; aembed_documents async	Async only	Vector store ingestion is often a one-shot batch script
Batching internal to subclass	Each provider chunks per its rate limits	Base class chunks	Provider rate limits and max-batch sizes vary widely

50+ subclasses cover OpenAI, Cohere, HuggingFace, Voyage, Vertex, Bedrock, plus local (sentence-transformers, FastEmbed, GPT4All).

Step-by-Step Walkthrough

Follow a typical operation through the embeddings/ module:

Caller invokes the public surface — usually .invoke(input) on a Runnable, or a legacy __call__(inputs_dict) on a Chain subclass.
Pydantic validation — every entry point is a BaseModel; constructor args, input dicts, and tool args_schema are validated before any expensive work runs. Fail-fast on type errors.
CallbackManager.configure — a fresh manager is built per call, fans on_*_start events to all subscribers (LangSmith tracer, stdout handler, custom logging), and stamps a UUID4 run_id for tree reconstruction.
embeddings-specific logic — the module's core method runs: prompt rendering, retrieval, tool execution, memory load, document split, etc. See the deep-dive sections above.
Provider call — typically a single HTTP request to OpenAI/Anthropic/etc., or a local SDK call. Retries are handled by tenacity with exponential backoff and a configurable max-attempts knob.
Streaming fan-out — if the provider streams tokens, each chunk fires on_llm_new_token through the callback manager so downstream observers (UI, log, tracer) see partial output.
OutputParser pass — if a parser is attached, the raw provider output is parsed into a structured Python object; OutputParserException may trigger a retry chain (RetryWithErrorOutputParser).
Memory write-back — for chains/agents that have a BaseMemory attached, save_context(inputs, outputs) persists the turn before returning to the caller.
on_*_end fan-out — the callback manager closes the run span; tracers serialise the Run tree and ship it to LangSmith asynchronously.
Result returned — caller receives a typed object (AIMessage, dict, BaseModel, list[Document], ...) matching the module's declared output schema.

What Could Go Wrong

Failure Mode	Trigger	Detection	Recovery
Provider 5xx / rate-limit	OpenAI/Anthropic/etc. transient error	HTTP status from SDK	tenacity retries with exponential backoff up to `max_retries`; then surface to caller
Output parser failure	LLM returned malformed JSON / wrong schema	`OutputParserException` in parser	`RetryWithErrorOutputParser` re-prompts with the parser error included; or surface
Pydantic validation	Caller passes wrong-shaped dict	`ValidationError` at `__init__` / `invoke`	Surface immediately — no fallback is correct here
Callback handler exception	User-supplied tracer raises	Try/except around each fan-out	Logged and swallowed by default; `raise_error=True` to opt in to propagation
Provider auth missing	`OPENAI_API_KEY` unset	SDK `AuthenticationError`	Surface with a helpful message; no retry (would just fail again)

Performance Profile

Hot Paths

Provider HTTP round-trip dominates wall-clock time (100ms–30s depending on model and prompt length).
Pydantic validation is repeated on every invoke; cached schema parsing keeps it under 1ms for typical inputs.
Callback fan-out is synchronous by default — a slow handler will slow every call. Async tracers (LangSmith) push work to a background thread to avoid blocking.

Resource Usage

Memory: token-history buffers (in memory/) and document caches (in retrieval pipelines) are the largest steady-state allocations.
I/O: bounded by provider rate limits; vector store I/O for retrieval-flavored modules.
Concurrency: async support via a* methods; agents and parallel chains use asyncio.gather for concurrent tool calls.

Directory Map

Source tree for embeddings

embeddings/
├── __init__.py
├── aleph_alpha.py
├── awa.py
├── azure_openai.py
├── baidu_qianfan_endpoint.py
├── base.py
├── bedrock.py
├── bookend.py
├── cache.py
├── clarifai.py
├── cloudflare_workersai.py
├── cohere.py
├── dashscope.py
├── databricks.py
├── deepinfra.py
├── edenai.py
├── elasticsearch.py
├── embaas.py
├── ernie.py
├── fake.py
├── fastembed.py
├── google_palm.py
├── gpt4all.py
├── gradient_ai.py
├── huggingface.py
├── huggingface_hub.py
├── infinity.py
├── javelin_ai_gateway.py
├── jina.py
├── johnsnowlabs.py
├── llamacpp.py
├── llm_rails.py
├── localai.py
├── minimax.py
├── mlflow.py
├── mlflow_gateway.py
├── modelscope_hub.py
├── mosaicml.py
├── nlpcloud.py
├── octoai_embeddings.py
├── ollama.py
├── openai.py
├── sagemaker_endpoint.py
├── self_hosted.py
├── self_hosted_hugging_face.py
├── sentence_transformer.py
├── spacy_embeddings.py
├── tensorflow_hub.py
├── vertexai.py
├── voyageai.py
└── xinference.py