GenAI Studio · Retrieval, embeddings & sources

Prepared September 14, 2026 · SDK source reviewed at c9e8b34 · Examples are teaching adaptations; authenticated gateway calls were not run for these pages.

What this capability does

Retrieval finds reference passages relevant to a question. Embeddings represent text as numerical vectors that can help find similar meanings even when wording differs. In a résumé translation application, this can connect a documented duty to useful civilian reference language.

Retrieval is a candidate-finding operation. A close match is not proof that a veteran has the job's qualifications. In particular, a reference listing a required license does not establish that the person holds that license.

Question or verified dutyAllowed reference setRanked passagesInspect sourcesGrounded draft

Choose one retrieval arrangement first

Arrangement	Who manages the index?	Application responsibilities
GenAI Studio knowledge base	The configured gateway ingestion/retrieval system	Curate documents, confirm indexing, select collection IDs, inspect search quality.
Application-controlled retrieval	Application code and the chosen vector store	Extract/chunk text, choose an embedding model, store vectors and metadata, filter access, retrieve, and supply passages to the model.
SQL lookup	The relational database	Match exact codes/IDs and return approved descriptions or mappings. Embeddings may be unnecessary for this step.

Start with built-in knowledge-base retrieval unless a measured need justifies custom indexing. Supabase can hold structured records even when GenAI Studio manages the vector index. You do not need two vector stores just because both products offer that feature.

Retrieve passages without generating an answer

Create and verify the collection using the knowledge-base guide. The SDK's retrieval factory returns a callable tool that can be used directly from Python; no agent loop is required for this inspection.

PYTHON · Example 01

import os
from genai_studio import GenAIStudio
from genai_studio.agents.tools import make_kb_search_tool

studio = GenAIStudio()
search = make_kb_search_tool(
    studio,
    os.environ["GENAI_STUDIO_KB_ID"],
    k=4,
)

result = search(query="Responsibilities involving equipment maintenance records")
if result.error:
    raise RuntimeError(result.error)

print(result.content)
for source in result.sources:
    print({
        "id": source.id,
        "title": source.title,
        "url": source.url,
        "distance": source.metadata.get("distance"),
    })

The tool calls POST /api/v1/retrieval/query/collection. It converts the returned documents, distances, and metadata into ToolResult.content, sources, and data. Missing metadata can produce missing titles or URLs; verify actual results instead of assuming every uploaded frontmatter field is preserved.

In the reviewed implementation, the default is dense retrieval with hybrid=False, and requested k is bounded between 1 and 20. The source documents a historical hybrid-mode issue on some gateway builds. Treat this as a reason to test the deployed system, not a permanent statement about all installations.

Code: retrieval tool implementationhttps://github.com/treese41528/genai-studio-sdk/blob/main/genai_studio/agents/tools/retrieval.py.

Understand the result before adding generation

Result detail	How to use it
Passage text	Decide whether it actually addresses the query and contains enough surrounding context.
Source ID/title/URL	Locate the original material and make the explanation reviewable.
Distance	A ranking diagnostic whose scale depends on the retrieval system. It is not a correctness probability.
No matches	An outcome to handle explicitly, rather than a reason to invent missing reference support.
Several similar passages	Check whether they are duplicates, conflicting versions, or complementary evidence.

Ask a literal question, a paraphrase, an acronym-heavy question, and an unrelated question. Write down which sources should be returned before inspecting results. That distinguishes retrieval evaluation from judging a fluent final answer.

If you need the application to display exactly the passages supplied to the model, perform retrieval explicitly, retain the returned IDs/text, and use that material in the generation request. A separate inspection query followed by chat(..., collections=[...]) can trigger another server-side retrieval; do not assume both retrieved sets are identical.

What an embedding is

An embedding maps text into a list of numbers. Texts with related meanings often occupy nearby positions in that model's vector space. The individual dimensions usually do not correspond to obvious human labels such as leadership or electrical expertise.

Text similarity is useful for finding candidates. It is insufficient for checking exact code identity, required credentials, employment eligibility, or whether a statement is supported. Keep those checks explicit.

The following is a small custom-retrieval experiment. It does not create a persistent index. Set GENAI_STUDIO_EMBED_MODEL to a model whose embedding endpoint you have tested.

PYTHON · Example 02

import os
from genai_studio import GenAIStudio

ai = GenAIStudio()
texts = [
    "Maintained equipment service records.",
    "Kept maintenance logs for vehicles.",
    "Prepared meals for a dining facility.",
]
response = ai.embed_complete(
    texts,
    model=os.environ["GENAI_STUDIO_EMBED_MODEL"],
)
vectors = response.embeddings
print("Model:", response.model, "Dimensions:", response.dimension)
print("Related wording:", ai.cosine_similarity(vectors[0], vectors[1]))
print("Different duty:", ai.cosine_similarity(vectors[0], vectors[2]))

There is no promised score for these examples. Inspect the actual output. The repository's embedding report is a dated capability probe: not every listed chat model supported embeddings, and dimensions differed. Verify current support instead of choosing the default chat model automatically.

Build an application-controlled index

Extract and inspect reference text. Keep document/version and location metadata.
Split it into passages that preserve useful meaning: a duty and its qualifiers should remain together.
Embed each passage using one selected model and configuration.
Store the vector with passage ID, source text, source/version, and access metadata.
Embed the question with the same model and compatible preprocessing.
Search within the authorized reference set, inspect the top results, and supply selected passages to generation.

Use the same embedding model for documents and queries. If the model changes, rebuild or version the index. Matching vector length alone does not make vectors from different models compatible. Verify the chosen database's dimension and index support before importing a large corpus.

In a shared system, apply access restrictions during retrieval, before private passages reach the model. Do not retrieve everyone’s documents and ask the model to ignore the unauthorized ones.

Store the right things in the right place

Data	Suggested treatment
Military and O*NET code relationship	SQL lookup with source/version and exact string fields.
Role description or employer requirement	Canonical text record or file, optionally indexed for retrieval.
Derived embedding vector	Regenerable index data tied to model and passage version.
Résumé evidence	Private case data with explicit access controls.
Similarity or retrieval distance	Diagnostic ranking output, not a personal suitability percentage.

If a user already selected a known occupation ID, SQL can fetch its description directly. Use semantic retrieval where wording varies or relevant sources are not known in advance. Add hybrid keyword/vector search only when examples demonstrate that it helps with exact terms, acronyms, or codes.

Evaluate retrieval and generation separately

For a small query set, label relevant passages. Precision@k asks how many of the top k returned passages are relevant. Recall asks how many known relevant items were found. Specify whether you count passages or documents, and handle duplicates consistently.

Then assess whether the final answer follows those passages. Good retrieval can still produce an unsupported answer, and poor retrieval can be hidden by a model's general knowledge. Keep both error categories in the review log.

Practical checks

Show five questions, the expected sources, returned passages, and a short relevance judgment. Include one exact code lookup that SQL handles better and one paraphrase where semantic retrieval helps. If adding retrieval does not improve the chosen task, keep the simpler baseline until the evidence changes.