多租戶支援中心檢索架構:具新鮮度感知的 Schema 設計
Tenant-Scoped Help Center Retrieval Architecture: Freshness-Aware Schema Design
多租戶 SaaS 支援中心的檢索架構應把文章、修訂版本和文字分塊分表保存,以 tenant_id 隔離資料,並由來源記錄重建檢索索引。候選檢索和重複項分組都要套用租戶條件;發布前須確認任務對應的仍是最新修訂版本,避免舊分塊進入可搜尋狀態。文章亦建議先以向量搜尋提出候選,再以標準化文字等確定性檢查確認重複項。
Short answer: keep canonical articles, revisions, and chunks in separate tables keyed by tenant_id, and build a freshness-aware retrieval index that can be rebuilt from those records. A small, stable chunk schema beats clever metadata when the job is finding semantically near-duplicate help-center records.
I started with one table containing article text, an embedding, and a tenant_id. It looked wonderfully simple. The first edit to a long troubleshooting guide changed every vector, though, and a stale chunk could still win a similarity search. Worse, a missing tenant predicate turned a deduplication query into a cross-customer data leak. Schema design is the control plane for both failures.
How should a multi-tenant SaaS help center retrieval architecture handle schema and freshness?
Treat the source article as the authority and the vector row as a disposable projection. The source has an immutable article_id within a tenant, a revision number, publication state, and an updated_at timestamp. Chunks carry the revision they came from. That single relationship makes an old vector detectable instead of mysterious.
Here is the shape I use in TypeScript before mapping it to SQL, a document store, or a hosted vector index:
type Article = {
tenantId: string;
articleId: string;
revision: number;
title: string;
body: string;
state: "draft" | "published" | "archived";
updatedAt: string;
};
type Chunk = {
tenantId: string;
articleId: string;
revision: number;
ordinal: number;
text: string;
contentHash: string;
embeddedAt: string | null;
};
The uniqueness boundary is (tenantId, articleId, revision, ordinal). The retrieval index should also store contentHash; on re-ingest, unchanged chunks can keep their embedding while changed chunks enter an explicit pending state. Do not use a title as identity. Support teams edit titles, and two products can legitimately have the same heading.
A tenant filter is required twice: when candidates are fetched and when duplicates are grouped. Relying on a post-filter is risky because approximate indexes may return a neighbor from another tenant before the application gets a chance to discard it. In one design review, a test fixture used the same article slug for two tenants; the grouping query joined on slug and reported a false duplicate. The fix was to make tenant_id part of every key and to assert the filter in the repository method, then add a fixture with identical titles, identical chunks, and different tenant IDs. Row-level security is useful where the database supports it, but it is a second line of defense, not a substitute for a parameterized predicate and tests. The important part is making the unsafe query hard to express: pass a tenant-scoped repository into the deduplication job instead of passing a global database handle and trusting every caller to remember one more condition.
Ship the smallest index.
What does a freshness-aware ingestion loop look like?
Split ingestion into deterministic stages: normalize, chunk, hash, embed, publish. Each stage records an input revision and an idempotency key. A worker can safely retry tenantId/articleId/revision; it should never silently replace a newer revision with an older result.
For a small service, a queue record can be as plain as this:
type EmbedJob = {
tenantId: string;
articleId: string;
revision: number;
requestedAt: string;
attempt: number;
};
function isCurrent(job: EmbedJob, article: Article): boolean {
return article.tenantId === job.tenantId &&
article.articleId === job.articleId &&
article.revision === job.revision;
}
The publish step checks that isCurrent is still true, then atomically marks the revision searchable. If an editor saves twice while an embedding request is running, the older job finishes harmlessly and the newer revision remains the only eligible one. “Fresh” is a query predicate, not a hope that a background worker is quick.
Measure the lag directly: time from article update to searchable revision, percentage of searches served by the latest revision, and the age of the oldest pending job. I’m not sure a universal freshness target exists; a legal-policy center may need seconds, while a slowly changing API glossary may accept hours. Your mileage will vary with publishing risk.
Why naive chunking creates false duplicate matches
Near-duplicate detection is sensitive to boundaries. Fixed 500-token windows split a code sample from its explanation; a semantic splitter can put a short heading in five different chunks after a minor edit. Both behaviors inflate the index and make “duplicate” mean “shares a boilerplate sentence.”
Keep heading ancestry and ordinal position as metadata, but compare at two levels. First, retrieve candidate chunks with a tenant-scoped vector search. Then aggregate scores by article and compare normalized text, title, and section path. A duplicate decision should require evidence from more than one chunk when an article is long.
I use a two-pass policy: a high-recall similarity threshold proposes pairs, and a deterministic check confirms them. The deterministic check can compare token overlap after removing navigation text, generated timestamps, and markup. Store the decision and the model/index version so a threshold change is an auditable migration rather than a silent rewrite.
The trade-offs that matter in production
| Choice | Useful when | Cost or limitation |
|---|---|---|
| Article-level embeddings | Short, self-contained FAQs | Misses duplicates hidden in long guides |
| Chunk-level embeddings | Long manuals and code-heavy docs | More rows, harder aggregation, more stale projections |
| Synchronous embedding on publish | Small corpus and strict freshness | Publishing latency depends on the embedding service |
| Asynchronous jobs | Burst edits or large tenants | Search can briefly lag; expose revision status |
| Shared physical index with tenant filter | Lower operational overhead | Isolation must be tested at the index and database layers |
| Separate index per tenant | Strong operational isolation | Many indexes and uneven resource usage |
The catch is that a single strategy is not suitable for every tenant. If one customer has millions of chunks, a shared index can create noisy neighbors; give that tenant a partition or a dedicated index. If an account requires immediate legal updates, stick with synchronous publication for those collections. For a tiny help center, plain full-text search plus a duplicate review queue may be the better engineering choice.
Operationally, watch recall on a hand-labeled set, false-positive rate per tenant, p95 query latency, embedding spend, and index growth. Log the tenant, article revision, chunk ordinals, and filter expression, but never log the raw private article body by default. A retrieval trace should let you reproduce a decision without becoming a second content database.
The Retrieval-Augmented Generation paper describes retrieval and generation as separate components; that separation is valuable here even when the final output is only a duplicate report. Keep generation out of the identity path. A language model can explain why two records look alike, but the source revision, tenant key, and stored similarity evidence decide what gets merged.
References
來源:DEV Community · dev.to