Bring your own model
Name a Hugging Face model in the template and deploy it in one click. Apply imports the model, serves it, embeds your documents with it and gives you a search over them, with no upload step and no serving code.
Applies empty and reads Four public-domain books from the starter sample set. Connect your own data before querying.
text your model embedsmatched by meaningcleared- apply, model import included
- 155 s / 255 s
- to deploy and run the sample
- $0.01
- dimensions per embedding
- 384
How these were measured
- 155 s / 255 s apply, model import included: Timed on production on 18 November 2026 in two fresh organizations, one on the enterprise plan and one on the free plan. Both imported the model from the Hub, served it, indexed the four sample books and answered a search.
- $0.01 to deploy and run the sample: Read from the billing meter for each of those two runs, model import, indexing and the search included.
- 384 dimensions per embedding: What BAAI/bge-small-en-v1.5 produces. A different model brings its own size, and the index follows it.
What’s inside
- Extractors
- bge small hf
- Retrievers
- document-search·feature_search
See it work
- a monster made in a laboratorydocument-search
ranked by your model's embedding of the query against each document
- a detective who notices small detailsdocument-search
the same model embeds both sides, so the comparison is like for like
- a miser visited by ghosts on Christmas Evedocument-search
returns documents, closest first
cleared- documents -> document-embeddings
- text your model embeds
- matched by meaning
- route: cleared
How it's wired
Applies 1 buckets, 1 collections and 1 retrievers today
Drag nodes to rearrange. Drag the background to pan, ctrl or cmd plus scroll to zoom. Click a node for its settings.
What it costs
Models
No catalog model is recorded for this template yet.
Collections and their documents
Reads text from content
| Field | Type | Required |
|---|---|---|
| document_id | string | set by Mixpeek |
| collection_id | string | set by Mixpeek |
mixpeek://bge_small_hf@v1
Retrievers
- document-searchfeature_search over document-embeddings; input query
Spend limits
- Daily spend budget in the manifest
- 1 USD a day; new batches pause once it is spent
- Acceptance run ceiling
- 0.5 USD
- Model cost
- No models recorded
Monthly cost at your volume is in the calculator. Served models start at zero replicas, so an idle namespace runs no model.
Reward signals
Nothing in this template writes signals back. It is the smallest setup that runs your own model end to end.
How reviewer decisions move the thresholds
None as shipped.
None from the application. Mixpeek records each retriever execution server-side, which logs the queries only.
mxp_retriever_executionsTo compare models, apply the template twice with two repos under two extractor names and run the same searches against both.
Your model, deployed like a built-in. The template names a Hugging Face repository and a pinned revision; apply imports it into your organization's model registry, checks it, serves it, and the collection and search below run on it.
- Swap the model by changing two lines: the repo and the revision. Everything downstream follows the extractor name.
- The revision is a commit, so every deploy of this file runs the same weights.
- Only safetensors weights are imported. Pickle files, which can run code when loaded, are skipped.
- The model scales to zero replicas when idle and starts again on the next call.
For: Teams that already chose an embedding model and want it indexed and searchable without running it themselves
- documents
- One object per document, with its text in content. The sample run uses four public-domain books.
- document-embeddings
- One document per object, carrying a 384-dimension embedding from BAAI/bge-small-en-v1.5.
- document-search
- A retriever that embeds the query with the same model and ranks the documents by similarity.
One file spins up the namespace. Generated from the workflow above. Also served at /templates/bring-your-own-model.namespace.yaml.
# bring-your-own-model: one manifest spins up the namespace.
# Platform manifest schema (GET /v1/discovery/schema). Validate with POST /v1/manifest/validate,
# apply with POST /v1/manifest/apply or the Deploy button. Wiring comes from the flow diagram:
# edges are bucket -> collection sources, collection -> retriever scope, retriever -> view.
# Applying a SECOND time, over a namespace this template already created: use
# POST /v1/manifest/apply?mode=create_missing, which creates what is missing and leaves
# what exists alone. The default, create_only, fails the WHOLE apply and rolls it back if
# any resource already exists, so an upgrade looks like a dead end without this. Use
# mode=upsert to also patch resources that exist but have drifted from this file.
version: '1.0'
metadata:
name: bring-your-own-model
description: "Namespace template bring-your-own-model. Generated from the flow diagram on mixpeek.com/templates/bring-your-own-model."
# The extractors the collections below run. A huggingface source is imported from the
# Hugging Face Hub at apply, into your organization's model registry, and served from it.
extractors:
- name: bge_small_hf
namespace: bring-your-own-model
version: v1
source:
huggingface:
repo: BAAI/bge-small-en-v1.5
revision: "5c38ec7c405ec4b44b94cc5a9bb96e735b38267a"
namespaces:
- name: bring-your-own-model
description: "Everything below lives in this namespace."
feature_extractors:
- name: bge_small_hf
version: v1
# Daily spend budget, in dollars of what you are charged (1,000 credits a dollar).
# New batches pause once the namespace has spent this much today; queries are not capped.
# Raise it later on the namespace: PATCH /v1/namespaces/<id> {"spend_budget": {"daily_usd": N}}.
budget:
daily_usd: 1
# Data sources. A storage connection carries credentials, so it is created in Studio
# (or POST /v1/organizations/storage-connections) and synced into the bucket named here.
# your-documents: manual, continuous, one object per document: its text in content -> bucket documents
buckets:
- name: documents
namespace: bring-your-own-model
description: "Meant to be fed by your-documents (manual, continuous): upload files here or write them through the API. Nothing arrives until you do."
schema:
properties:
content:
type: text
collections:
- name: document-embeddings
namespace: bring-your-own-model
description: "Each document embedded by bge_small_hf, the Hugging Face model BAAI/bge-small-en-v1.5 that this manifest imports. Feeds document-search."
source:
type: bucket
bucket: documents
feature_extractor:
name: bge_small_hf
version: v1
input_mappings:
text: content
field_passthrough: []
enabled: true
retrievers:
- name: document-search
namespace: bring-your-own-model
description: "Type a question or a description and get the documents whose meaning is closest, ranked by your model's embeddings."
collections:
- document-embeddings
input_schema:
query:
type: text
required: true
description: "What to look for; searched across every index below"
stages:
- stage_name: search
stage_id: feature_search
parameters:
searches:
- feature_uri: "mixpeek://bge_small_hf@v1"
query:
input_mode: text
value: "{{INPUT.query}}"
top_k: 10
fusion: rrf
final_top_k: 10
tags:
- template:bring-your-own-model
alerts:
- name: document-search-returning-nothing
namespace: bring-your-own-model
description: "Emails the org notifications address (Settings -> Notifications; unset means opted out) when document-search has come back empty on its last five runs: the searches are matching no document, so the documents or their embeddings need a look."
source: system
system_condition:
type: retriever_no_results
params:
min_samples: 5
notification_config:
channels:
- channel_type: email
include_matches: true
include_scores: true
enabled: true
# Four public-domain books from the starter sample set, embedded by the Hugging
# Face model the extractors section imports, and the search they must answer.
seed:
- bucket: documents
max_objects: 4
objects:
- blobs: {content: samples/starter/texts/frankenstein.txt}
- blobs: {content: samples/starter/texts/a-christmas-carol.txt}
- blobs: {content: samples/starter/texts/alice-in-wonderland.txt}
- blobs: {content: samples/starter/texts/adventures-of-sherlock-holmes.txt}
acceptance:
max_cost_usd: 0.5
steps:
- name: documents-embedded-by-your-model
kind: documents
collection: document-embeddings
expect: {min_documents: 4}
- name: your-model-answers-a-search
kind: query
retriever: document-search
inputs: {query: a monster made in a laboratory}
expect: {min_results: 1}Read from the manifest, so a part it ships commented out never shows as ready.
What each part needs
- document-embeddings
- Deploys and processes documents as they arrive.
- document-search
- Deploys and answers queries once its collections hold documents.
- feature_search
- The one-click manifest includes this stage, and every search runs from a text query.
- your-documents
- You upload these files yourself. There is no connection to sync.
| Component | Role | Source | Today |
|---|---|---|---|
| bge_small_hf (BAAI/bge-small-en-v1.5) | The extractor this template brings: a Hugging Face sentence-transformers model, imported at apply and served from your organization's model registryMIT licensed. Replace the repo and revision with any sentence-transformers model whose weights are safetensors. | You supply | Deploys ready |
| feature_search | Embeds the query with the same model and ranks documents by similarity | Built in | Deploys ready |
Apply the manifest; the model is imported from the Hub into your organization and served at zero replicas until the first call.
The same manifest applies against a customer-hosted deployment, which pulls the model from the Hub at apply.
- Permissions
- A key with namespace and collection create. A gated or private repo also needs an organization secret holding a Hugging Face token, named in token_secret.
- Footprint
- One 384-dimension index, one document per object. The model snapshot counts against the 5 GB model limit; bge-small is about 130 MB.
Four public-domain books, seeded on deploy. The acceptance block checks that all four are embedded by your model and that a search returns a result.
| Category | Rule |
|---|---|
| Model import | Apply refuses a branch revision, a repo with only pickle weights, a snapshot over 5 GB and a repo missing config.json or modules.json, before anything is created. |
| Indexing | Every seeded object becomes one document in document-embeddings. |
| Search | document-search answers with at least one result for the sample query. |
Unmeasured beyond the sample. bge-small is a small model; throughput depends on the model you name.
Which plans can bring a model this way?+
Every plan, free included. A Hugging Face model named in a template is imported at apply on any plan. Uploading a private model archive (the Models page and /v1/models/uploads) is an Enterprise feature.
Which models work?+
Sentence-transformers models on the Hugging Face Hub whose weights are safetensors, with config.json and modules.json at the repo root and a snapshot under 5 GB. Validate tells you before anything is created if a repo does not qualify.
Why is the revision a commit and not main?+
A branch moves. Pinning a commit (or a tag) means every deploy of this file imports the same weights, so a search that worked yesterday is answered by the same model today. Apply refuses a branch for that reason.
How much of a long document does the model read?+
As much as the model takes. bge-small reads the first 512 tokens of each document, so a whole book is represented by its opening pages. Split long text into passages, one object each, when the whole of it has to be searchable.
Can I use a private or gated model?+
Yes. Store a Hugging Face access token as an organization secret and name it in token_secret on the model. A public repo needs no token.