How do you build a private knowledge assistant with the Plugsky RAG API?

Key facts

Embeddings	POST /v1/embeddings with plugsky-embed family models
Generation	POST /v1/chat/completions with plugsky-pro or another catalogue model
Knowledge/RAG	Knowledge and RAG capabilities are available on paid platform plans
Files API	POST /v1/files is coming soon; ingestion lives in the dashboard today
Vector storage	Any vector store; match the live model dimension from /models
PII default	Embeddings default to no-PII with automatic redaction
Residency	Region pinning plus VPC, on-prem and air-gapped options
Product status	Live (RAG and embeddings); Files API coming soon

TL;DR

• RAG is retrieval plus generation: embed once, retrieve per query, generate grounded.
• Keep embeddings and chat inside one region and one project.
• Chunk by structure, store source metadata, and filter by tenant.
• Evaluate retrieval before blaming the generation model.
• The Files API is coming soon; dashboard ingestion works today.

How it works, step by step

1. Decide the corpus and the questions the assistant must answer, then write an eval set.
2. Ingest documents and chunk them by headings, paragraphs and tables.
3. Embed chunks with the plugsky-embed family and store vectors plus metadata.
4. Build retrieval with tenant filters, top-k search and a similarity threshold.
5. Compose a grounded prompt that requires citations and refuses unsupported answers.
6. Generate with plugsky-pro and stream results to the interface.
7. Measure retrieval hit rate and answer faithfulness, then iterate on chunking.

Original data

Try it yourself

Open the RAG sandbox →

Pipeline architecture

Keep the pipeline boring and observable. Ingestion writes chunks and vectors; retrieval returns candidates; generation consumes only candidates and cites them. Each stage should be independently testable — if you cannot tell whether a bad answer came from missing retrieval or poor prompting, you cannot improve the system.

vec = client.embeddings.create(model="plugsky-embed", input=[query]).data[0].embedding
hits = store.search(vec, top_k=8, filter={"tenant_id": tenant_id})
context = "\n\n".join(f"[source: {h.source}]\n{h.text}" for h in hits)
answer = client.chat.completions.create(
    model="plugsky-pro",
    messages=[
        {"role": "system", "content": "Answer only from the sources and cite them."},
        {"role": "user", "content": f"{context}\n\nQuestion: {query}"},
    ],
)

Keeping the assistant private

• Region pinning: embed and generate in the region that satisfies your data rules, and keep the vector store there too.
• Tenant isolation: partition collections by tenant or use a hard metadata filter on every query.
• PII posture: embeddings default to no-PII mode with automatic redaction; select the mode deliberately rather than by accident.
• Least privilege: separate keys for ingestion and query, each with only the scopes it needs.
• Auditability: log request IDs, model IDs, regions and retrieval sources so answers can be reconstructed.

For stricter requirements, VPC, on-prem and air-gapped deployments keep prompts, embeddings and logs inside your own perimeter.

Retrieval quality beats prompt tricks

Most disappointing assistants fail at retrieval. Chunk lengths that split sentences, missing metadata, and a top-k that ignores similarity scores all produce confident nonsense. Start with structured chunking, keep section titles in each chunk, and add hybrid keyword search for identifiers, invoice numbers and error codes. Rerank the top candidates before generation if precision matters. Then build a small labelled eval set of question-and-source pairs and measure hit rate at k — the number that predicts answer quality far better than any prompt rewrite.

From prototype to production

Production adds lifecycle concerns: re-indexing when documents change, deletion when a customer leaves (vectors included), cost visibility per tenant, and graceful behaviour when retrieval returns nothing. A refusal path — "the knowledge base does not cover this" — is a feature, not a failure. Use scoped keys and audit logs for governance, and check /docs for dashboard ingestion and the Files API status as it evolves.

Honest comparison

Capability	Plugsky RAG	Prompt-stuffing only	Self-hosted RAG stack
Embeddings	plugsky-embed family via /v1/embeddings	Model context window only	You run embedding servers
Retrieval	Vector search with metadata filters	None	You operate the vector DB
Residency	Region pinning plus VPC/on-prem options	Whatever the API provides	Fully in your control
PII posture	No-PII default for embeddings	Manual	You implement redaction
Ops burden	Managed ingestion and inference	Low but limited	High
Files API	Coming soon; dashboard ingestion today	Not applicable	Your pipeline

Frequently asked questions

Is Plugsky RAG generally available?

Knowledge and RAG capabilities are available on paid platform plans, with embeddings live on /v1/embeddings. The raw Files API is coming soon; dashboard ingestion is the current path.

Which embedding model should I use for RAG?

plugsky-embed for English-dominant corpora; plugsky-embed-multilingual when content mixes languages such as Arabic and English. Read the live dimension from /models before creating a collection.

Can I keep the whole pipeline in one region?

Yes. Pin the workspace region so inference, embeddings and logs stay put, and host your vector store in the same region. VPC, on-prem and air-gapped deployments go further for regulated workloads.

How do I stop the assistant making things up?

Ground the prompt in retrieved passages, require citations, and add a refusal path when retrieval is empty or below a similarity threshold. Measure faithfulness against a labelled eval set.

Does Plugsky store my documents?

Ingestion through the platform keeps your content in the selected region under the platform's data handling terms. For full infrastructure control, use a VPC or on-prem deployment and host vectors yourself.

How do I handle document updates?

Track content hashes per chunk and re-embed only what changed. Re-index in the background and version collections so you can roll back a bad ingestion run.

What about deleting a customer's data?

Delete source records, derived chunks and vectors together, and keep evidence of the deletion. Vectors are derived personal data when the source contains it; treat them the same way.

Should I stream answers in the UI?

Yes. Streaming improves perceived latency and works with the same chat completions call. Keep citations rendered alongside the stream so users can verify claims.