1.  [](/)
2.  [Templates](/templates)
3.  Bring your own model

Model data

v1.0 · updated 2026-11-19

# 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.

[Deploy this namespace](https://studio.mixpeek.com/manifests/apply?url=https%3A%2F%2Fmixpeek.com%2Ftemplates%2Fbring-your-own-model.namespace.yaml&manifest_url=https%3A%2F%2Fmixpeek.com%2Ftemplates%2Fbring-your-own-model.namespace.yaml&src=template-bring-your-own-model&template=bring-your-own-model&template_name=Bring+your+own+model&sync=1&utm_source=homepage&utm_medium=template_deploy&utm_campaign=mvs_onramp)[Book a workshop](/pilot?src=template-bring-your-own-model)View manifest

What deploys today3 ready1 need your input

Applies empty and reads Four public-domain books from the starter sample set. Connect your own data before querying.

![The title page of the 1818 first edition of Frankenstein, with the subtitle The Modern Prometheus and an epigraph from Paradise Lost](/templates/bring-your-own-model/title-page.webp)text your model embedsmatched by meaningcleared

documents -> document-embeddings · One of the four sample books. The model you name reads each document's text and embeds it; a search is embedded by the same model and compared against it.Still: Wikimedia Commons (public domain) / Frankenstein, 1818 first edition

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](/retrievers/feature_search)

## See it work

*   a monster made in a laboratory
    
    document-search
    
    ranked by your model's embedding of the query against each document
    
*   a detective who notices small details
    
    document-search
    
    the same model embeds both sides, so the comparison is like for like
    
*   a miser visited by ghosts on Christmas Eve
    
    document-search
    
    returns documents, closest first
    

Simulated walkthrough · illustrative frames, scripted decisions

Pause

![The title page of the 1818 first edition of Frankenstein, with the subtitle The Modern Prometheus and an epigraph from Paradise Lost](/templates/bring-your-own-model/title-page.webp)text your model embedsmatched by meaningcleared

documents -> document-embeddingsStill: Wikimedia Commons (public domain) / Frankenstein, 1818 first editionframe 1 of 1

Detections on this frame

*   text your model embeds
*   matched by meaning

Decision path

1.  documents -> document-embeddings
2.  text your model embeds
3.  matched by meaning
4.  route: cleared

embedded by the imported model, searchable

Running tally

1

cleared

0

review

0

excluded

What a person's call does here

None as shipped.

Try a search

“a monster made in a laboratory”“a detective who notices small details”“a miser visited by ghosts on Christmas Eve”

Pick a search to see which retriever answers it and whether it works on a one-click deploy.

IndocumentsOutdocument-embeddingsdocument-search

## How it's wired

Applies 1 buckets, 1 collections and 1 retrievers today

SourceBucketCollectionRetrieverAlertNot applied yet

.wf-flow { stroke-dasharray: 6 6; animation: wf-dash 1.2s linear infinite; } @keyframes wf-dash { to { stroke-dashoffset: -12; } } @media (prefers-reduced-motion: reduce) { .wf-flow { animation: none; } } SOURCENeeds your inputyour-documentsmanual · continuousBUCKETdocumentscontent: text · dedupCOLLECTIONDeploys readydocument-embeddingsbge\_small\_hf@v1RETRIEVERDeploys readydocument-searchtop 10ALERTdocument-search-returning…

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

document-embeddingsfrom bucket documents, by bge\_small\_hf@v1

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-search
    
    feature\_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](#pricing). 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

Docs[Interactions API](https://mixpeek.com/docs/retrieval/interactions)

Explicit signals

None as shipped.

Implicit signals

None from the application. Mixpeek records each retriever execution server-side, which logs the queries only.

Where they land

`mxp_retriever_executions`

How the loop closes

To compare models, apply the template twice with two repos under two extractor names and run the same searches against both.

OverviewManifestWhat deploysComponentsDeploymentEvaluationQuestions

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

What goes in

documents

One object per document, with its text in content. The sample run uses four public-domain books.

What comes out

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.

Docs[Manifest extractors](https://mixpeek.com/docs/operations/manifests)

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.

document-embeddingsCollectionDeploys ready

document-searchRetrieverDeploys ready

feature\_searchRetriever stageDeploys ready

your-documentsData sourceNeeds your input

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.

Docs[Feature search](https://mixpeek.com/docs/retrieval/stages/feature-search)

Component

Role

Source

Today

[bge\_small\_hf (BAAI/bge-small-en-v1.5)](https://huggingface.co/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](/retrievers/feature_search)

Embeds the query with the same model and ranks documents by similarity

Built in

Deploys ready

Docs[Customer-hosted overview](https://mixpeek.com/docs/customer-hosted/overview)

Mixpeek cloud

Apply the manifest; the model is imported from the Hub into your organization and served at zero replicas until the first call.

Your own cloud

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.

Docs[Retriever execution traces](https://mixpeek.com/docs/retrieval/retrievers)

Reference fixtures

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.

Throughput

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.