Reference

How to configure the embedding provider

Configure and validate the embedding path Buffaly uses for semantic search, semantic databases, memory/entity discovery, and ontology-related lookup behavior.

Who this is for

Use this article when semantic search or discovery depends on vector similarity and you need to verify whether the problem is credentials, indexing, database state, or the query itself.

Make session semantic search return meaningful matches.

Troubleshoot missing or stale semantic search results.

Configure OpenAI credentials used by embedding-dependent features.

Understand embeddings, SemDB, fragments, memory, ontology, and action/entity discovery.

Quick answer

The active source currently shows embeddings as a separate dependency on Buffaly.AIProviderAPI. The session-semantic path calls Buffaly.AIProviderAPI.Embeddings.GetEmbeddingsWithTokens(...) and stores vectors for text-embedding-3-small.

Current model

text-embedding-3-small

Dimensions

1536

Credential path

Treat OpenAI API configuration as the documented path unless deployment source proves otherwise.

Do not infer that ChatGPT or Codex backend auth automatically configures embeddings. Verify OpenAI API-key status and run an embedding-backed search or indexing test.

What embeddings are used for

Session semantic search

Completed user/assistant turns are indexed into fragments and embedded so prior conversations can be searched by meaning.

Session semantic reindexing

The scheduled reindex process can import recent SQL session messages and call the indexer with GenerateEmbeddings = true.

Semantic database fragments

Buffaly.Agent.Tools.SemanticDatabase calculates embeddings for fragments when inserting or refreshing lookup data.

Discovery support

Embedding-backed fragment stores support similarity search for semantic data, ontology-backed discovery, actions, and entities.

Embeddings are not the same as normal completions. A provider/model that can answer chat messages does not prove embedding-dependent features are configured.

Current provider requirement from source

The most direct session semantic source is Buffaly.SessionSemanticDatabase/SessionSemanticIndexer.cs. It defines the current embedding model, expected dimensions, query/fragment embedding calls, and vector storage flow.

LocalSessionSemanticEmbeddings.CurrentEmbeddingModel is text-embedding-3-small.
ExpectedDimensions is 1536.
Query and fragment embedding both call Buffaly.AIProviderAPI.Embeddings.GetEmbeddingsWithTokens(...).
Fragment vectors are stored through FragmentVectorsNativeRepository.Upsert(...) and an Embeddings row keyed by model.

This page cannot honestly claim a general embedding provider catalog from the current product implementation. If a future deployment adds another embedding provider, verify the source or assembly that replaces AIProviderAPI.Embeddings before documenting it as supported.

Credentials and settings to check

Start with OpenAI API credentials, not ChatGPT or Codex backend credentials.

Open the Buffaly settings UI for the target installation.
Check OpenAI API-key status without revealing the key.
Confirm OpenAIFeature loads the database-backed OpenAI Feature row and normalizes ApiKey.
Confirm BuffalyAgentSettingsService owns OpenAI key status, save, and delete operations.
Run an embedding-backed smoke test instead of assuming a completion smoke test proves embeddings work.

Do not store embedding credentials in prompts, wiki pages, .pts files, task artifacts, screenshots, or ordinary memory.

Database and indexing pieces involved

Piece	Documented role
SemanticConversationReindexScheduledProcessHandler	Reads SQL session messages, pairs turns, and calls the indexer.
SessionSemanticIndexer	Creates root, turn, user, and assistant fragments and optionally generates embeddings.
EmbeddingsRepository	Stores or looks up embedding model rows such as `text-embedding-3-small`.
FragmentVectorsNativeRepository	Stores native fragment vectors for similarity search.
SessionConversationSearchDriver	Embeds query text and searches fragments by similarity, exact text, or hybrid behavior.
semantic-conversation-search.html	User-facing search page that notes automatic indexing and shows reindex status where available.

A failure in any layer can look like semantic search is broken, so verify credentials, database rows, scheduled process status, fragment counts, vectors, and query behavior separately.

How to test embeddings

1. Verify OpenAI key status

Ask Buffaly to inspect the OpenAI Feature/settings status and report only whether a key is present.

2. Verify reindex status

Inspect latest processed message/time, imported sessions/turns, failed sessions, and whether embeddings were generated.

3. Run controlled search

Use a known recent phrase or topic, then verify the top result by reading exact session history or a committed file.

4. Inspect index path

If indexing is suspect, check scheduled process status and whether vectors exist for recent fragments before changing credentials.

GET /api/semantic-conversation-search/reindex-status

How to ask Buffaly to configure or diagnose embeddings

Configure embeddings for session semantic search. First inspect source to confirm the current embedding provider path, then verify OpenAI API-key status, semantic reindex status, and one semantic search result. Do not reveal or commit secrets.

Diagnose why semantic conversation search returns no results. Check OpenAI Feature key status, Buffaly.AIProviderAPI.Embeddings errors in logs, reindex process status, fragment/vector counts, and whether the query is too narrow.

Verify whether this installation still requires OpenAI for embeddings. Inspect SessionSemanticIndexer, semantic database tools, provider docs, and runtime settings. If source cannot prove an alternate provider, say so explicitly.

Common failures and troubleshooting

OpenAI API key is missing

Configure the OpenAI API key through the supported settings path and retest. Do not use a ChatGPT password or Codex profile as a substitute unless deployment source proves embeddings use that route.

Completion works, semantic search does not

Completion and embedding providers are separate. Check API-key status, embedding logs, and semantic reindex status.

Old results but not recent work

The scheduled reindex process may not have processed recent messages. Check latest processed time and use exact history search as a fallback.

Exact search works, semantic search is empty

Exact fragment search can work without valid vectors. Verify embedding generation and FragmentVectorsNative rows.

Model or dimension mismatch

Source expects text-embedding-3-small with 1536 dimensions. If the model changes, verify vector dimensions and similarity functions before mixing vectors.

External provider behavior is unclear

If credentials appear configured but embedding calls fail, inspect deployed assembly config, logs, and installation paths instead of guessing from wiki text.

Providers and authentication Secrets handling Semantic data and ontology Ontology and ProtoScript Session semantic search Search session history Settings and feature flags