Key facts
| API compatibility | OpenAI-shaped /v1/embeddings and /v1/chat/completions (live) |
| Embeddings | plugsky-embed and plugsky-embed-multilingual (live) |
| Ranking | Deterministic scoring and rules in your code |
| Optional explanations | JSON mode for reasons per recommended item (live) |
| Models | 30+ models behind one endpoint when generation is needed |
| Migration | Base URL and model names; re-embed the catalogue once |
| Pricing | Flat monthly plans with unlimited fair-use usage on self-serve |
| Free tier | plugsky-micro and plugsky-lite on the free plan, no card required |
TL;DR
- One client serves both catalogue embeddings and conversational refinement.
- Re-embed the catalogue when switching embedding models — spaces cannot be mixed.
- Keep ranking, eligibility and pricing deterministic in your services.
- Use JSON mode only for optional explanations, never for compliance decisions.
- Shadow-run against your current engine before switching traffic.
How it works, step by step
- Inventory where embeddings are used today — indexing, query encoding or both — and record model and dimensions.
- Move base URL, key and model names into configuration and create scoped keys for indexing and serving.
- Re-embed the catalogue with plugsky-embed (or plugsky-embed-multilingual) into a new collection with the same metadata fields.
- Point query-time embedding at the same model, keeping filters and ranking untouched.
- Optionally add JSON-mode explanations grounded in item attributes, generated after ranking.
- Shadow-run both stacks on real traffic and compare acceptance, coverage and latency.
- Switch by configuration, keep the old collection for rollback, and monitor usage and quality metrics.
Try it yourself
Open the OpenAI-compatible API tester →
One client for catalogue and conversation
Recommendation systems need embeddings far more often than they need chat. An OpenAI-compatible endpoint covers both with one client: embeddings for catalogue indexing and query encoding, chat completions when you want conversational refinement or generated reasons. That keeps your serving stack small and your integration surface predictable.
Plugsky runs both endpoints live, so existing pipelines keep their structure. Where you would otherwise wait on managed conveniences — files, batch and assistants-style endpoints are coming soon — keep bulk catalogue jobs in your own schedulers and call the live endpoints per batch.
Migrating an existing recommender
The software migration is small; the data migration is the project. Record your current embedding model and vector dimensions, backfill a new collection with the replacement model, and verify retrieval quality before serving from it. Mixed vector spaces produce nonsense rankings that look like model failure but are actually an indexing mistake.
- Backfill first: build the new collection completely before switching reads.
- Verify coverage: confirm every catalogue item has a vector and metadata.
- Keep metadata stable: identical filter fields make the comparison meaningful.
- Retain rollback: keep the old collection until the new one beats it on your metrics.
Evaluation and rollout
Compare the two engines on the same traffic. Track acceptance rate, return rate, catalogue coverage, diversity and latency, and segment by user type — new versus returning users often behave differently because content-based retrieval handles cold start well.
Add generated explanations only after ranking is stable, and treat them as presentation, not policy. Every request should be traceable: candidates retrieved, filters applied, scores computed and the final order. Because provider selection lives in configuration, rollback and future moves are deploys rather than rewrites. Where customer data is region-bound, pin the workspace to a region-locked plane or deploy VPC, on-prem or air-gapped with the same client code.
Honest comparison
| Aspect | Plugsky | Staying on OpenAI | Separate vendors |
|---|---|---|---|
| Client code | One compatible client | No change | Adapter per service |
| Embeddings | plugsky-embed and plugsky-embed-multilingual (live) | Existing model | Varies |
| Ranking | Deterministic, stays in your code | Same | Same |
| Pricing | Flat monthly with unlimited fair use on self-serve | Per-token | Mixed bills |
| Residency | Region choice, VPC, on-prem, air-gapped | Limited options | Varies by vendor |
Frequently asked questions
Do we need chat models for recommendations?
Usually not for ranking. Embeddings plus deterministic rules deliver the core feature; chat models add conversational refinement or generated explanations when you want them.
Why re-embed the catalogue?
Embedding spaces are model-specific. Documents embedded with one model cannot be compared against queries embedded with another, so a full backfill is required when providers change.
Can we keep our current vector database?
Yes. Plugsky returns standard float vectors. Any store that accepts embeddings works; only the embedding call changes.
How do we return explanations?
Generate them after ranking with JSON mode, grounded in item attributes. Explanations describe the ranked list; they must never change eligibility or compliance decisions.
What about catalogue languages?
Use plugsky-embed-multilingual so one collection serves queries in multiple languages, which is common in GCC markets where Arabic and English content mix.
How do we validate the migration?
Shadow-run both engines on live traffic and compare acceptance, coverage, diversity and latency before switching reads. Keep the old collection for instant rollback.
Can this run on-prem?
Yes. Plugsky supports region-locked cloud planes plus VPC, on-prem and air-gapped deployment, so catalogue and customer data can stay within your environment.