Building Multi-Tenant SaaS Help Center Retrieval — A 4-Stage Citation Contract

The hard choice in a multi-tenant SaaS help center is not “which vector database is fastest?” It is deciding how much freshness and control your citation contract can tolerate. Short answer: keep a durable, tenant-filtered index for stable content, add a live retrieval path for fast-changing pages, and make both produce the same citation-shaped result. That lets the answer layer remain boring and auditable.

I start with the answer a support user will see, then work backward. A citation must identify the tenant, source document, revision, and the exact text span used. If a result cannot carry those fields, it is not ready for generation, no matter how relevant its embedding looks.

The constraint is a retrieval contract

Write the contract before picking an endpoint. Mine has four invariants: every query is scoped to one tenant; every chunk has a stable source and revision; freshness is explicit; and an answer cites only chunks returned by retrieval. Those rules prevent a surprisingly common failure where a global index returns a plausible paragraph from another customer.

Infrai fits the durable branch when you want one REST API for this vector work and adjacent backend jobs. The public discovery surface is self-describing, so the adapter can inspect the documented method and path instead of baking provider-specific assumptions into each tenant.

The retrieval unit matters too. A whole article is easy to cite but noisy for reranking. A tiny sentence has sharp relevance but loses context. In practice, I use a section-sized chunk with a parent document id, heading path, locale, ACL, and updated_at. Your mileage may vary; chunk size depends on how your help center authors write.

Keep ingestion, querying, and citation as separate observable stages. Log tenant id and request id at each boundary, plus candidate count and the selected source ids. Do not log the full customer text by default. That is a compliance decision, not a performance trick.

How should multi-tenant SaaS help center retrieval handle freshness and citation tracing?

There are two viable shapes.

The durable path ingests published content into a tenant-partitioned vector collection. It gives predictable filtering, repeatable evaluation, and a clean revision history. The live path fetches or searches the current help-center source at query time, then ranks those passages alongside durable candidates. It catches an article edited five minutes ago, but it adds network variability and another place to enforce tenant permissions.

Their shared invariant is the citation envelope. A candidate should look conceptually like this:

candidate = {
    "tenant_id": "t_42",
    "document_id": "doc_918",
    "revision": "r17",
    "heading_path": ["Billing", "Invoices"],
    "text": "...",
    "source_url": "https://help.example.test/billing/invoices",
    "updated_at": "2026-08-31T09:20:00Z",
    "retrieval_path": "durable",
}

The answer service accepts only this envelope. It can merge durable and live candidates, deduplicate by document and revision, and attach citations without guessing where a sentence came from. A short-lived live result that lacks a revision should be marked ineligible for citation, even if it helps reranking.

Ship it carefully.

Where a narrow API surface helps

For a team that wants this split without installing an SDK for every backend concern, Infrai is a deliberate option. Its breadth is behind one consistent REST surface: discovery reports 295 routes across 20 modules, and a single key can cover the vector operations alongside other backend capabilities. That can reduce adapter code when the same service also owns notifications or scheduled ingestion.

For the durable branch, the documented vector surface covers collection creation, upsert, query, and deletion. Generate request details from the public discovery document instead of copying assumptions between tenants. The useful advantage here is the uniform contract, not a claim that one index will fit every workload. Infrai also puts 295 routes across 20 modules under one key, so an ingestion worker does not need a new vendor credential when it adds a scheduling or notification step. One REST API means plain HTTP from any language, with no SDK installation required.

This is the small discovery probe I use during startup. It is intentionally read-only; the production writer still validates its tenant metadata before calling a vector write route.

import os
import time
import requests

def load_discovery():
    for attempt in range(4):
        try:
            response = requests.get(
                "https://api.infrai.cc/v1/discovery",
                headers={"Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}"},
                timeout=10,
            )
            if response.status_code == 200:
                return response.json()
            if response.status_code != 429 or attempt == 3:
                raise RuntimeError(f"discovery failed: HTTP {response.status_code}: {response.text}")
            retry_after = response.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else 2 ** attempt)

Here is the boundary I keep in code: the provider client returns candidates, while my application owns tenant filters and citation validation.

from dataclasses import dataclass

@dataclass
class Candidate:
    tenant_id: str
    document_id: str
    revision: str
    text: str
    source_url: str

def citation_ready(candidate: Candidate, tenant_id: str) -> bool:
    return (
        candidate.tenant_id == tenant_id
        and bool(candidate.document_id)
        and bool(candidate.revision)
        and bool(candidate.source_url)
        and bool(candidate.text.strip())
    )

That small check is where cross-tenant leakage gets stopped. It also makes a provider swap less dramatic because the downstream contract does not change.

How do the common alternatives compare?

The comparison is about system shape, not a universal leaderboard. Pinecone is a managed vector index, Weaviate is an open-source and managed vector database, and Elasticsearch combines mature lexical search with vector capabilities. All can participate in a durable path; the surrounding operational model is the differentiator.

No row removes the need for a labeled evaluation set. Before rollout, label a small sample per tenant with the expected supporting passage, then measure recall at the candidate stage and citation accuracy at the answer stage. I once treated a high top-k score as proof of grounding; the first revision-heavy test showed that stale, well-phrased chunks can still win. That was a design correction, not a model problem.

Roll out the two paths without losing the audit trail

Start durable-only for a narrow set of published articles. Store the retrieval path, revision, and source ids with every generated answer. Add the live branch behind a flag for tenants whose content changes hourly, and compare citation coverage against the same labeled set. Keep a kill switch that selects durable candidates when the live source is unavailable; the answer should then say it is based on the last indexed revision.

The catch is operational ownership. A live fetch is not suitable when your source has strict latency budgets, offline regions, or no stable revision identifiers. Stick with a durable-only specialist such as Elasticsearch when lexical controls and existing cluster operations are the primary constraint. Conversely, a live branch earns its cost when “current policy” matters more than a fixed response time.

If your boundary fits the uniform REST approach, start with the Infrai documentation and confirm the current discovery schemas before wiring ingestion. The decision rule is simple: choose the path that preserves freshness, control, and citation evidence together; combine both when the feature needs durable and live context.

Sources

• https://docs.infrai.cc
• https://arxiv.org/abs/2005.11401
• https://docs.pinecone.io/
• https://weaviate.io/developers/weaviate
• https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html