Semantic Search

Semantic search uses a sentence embedding model to understand the meaning of queries, not just keyword matches. When a user searches for "how do I change colors", it finds the theming page even if it never uses the word "colors".

Enable Semantic Search

[search]
semantic = true

That's it. Oxidoc bundles a default embedding model — no downloads, no API keys, no external services.

How It Works

Build Time

1. Oxidoc loads the embedding model (bundled BGE Micro v2 or your custom model)
2. Every page's text content is embedded into a 384-dimensional vector
3. The vectors are written to search-vectors.json in the output
4. The model file is copied to search-model.gguf in the output

Query Time (In Browser)

1. The browser fetches the model file and pre-computed vectors
2. The model initializes in Wasm (CPU-only, no GPU)
3. When the user triggers semantic search, the query text is embedded in real-time
4. Cosine similarity is computed between the query vector and all page vectors
5. Results are ranked by similarity and merged with lexical results via RRF

All computation happens in the browser. No data leaves the user's machine.

Hybrid Ranking

When semantic search is enabled, Oxidoc runs both engines on every "Ask AI" query and merges results using Reciprocal Rank Fusion (RRF):

graph LR
    Q[User Query] --> L[Lexical / BM25]
    Q --> S[Semantic / Cosine Similarity]
    L --> F[RRF Fusion]
    S --> F
    F --> R[Ranked Results]

Pages appearing in both result sets get combined scores. A page that matches keywords and is semantically relevant ranks highest.

Why 70/30?

Documentation search is keyword-heavy — users often search for exact function names, config fields, or error messages. The 70% lexical weight ensures these exact matches always surface. The 30% semantic weight adds recall for conceptual queries without drowning out precise keyword results.

The Default Model

Oxidoc bundles BGE Micro v2 — a compact sentence embedding model by BAAI:

Why This Model?

Limitations

• Optimized for English — for non-English documentation, use a custom model
• 384 dimensions — larger models with higher dimensions may capture more nuance, at the cost of size
• 17.5 MB browser download — users on slow connections may experience a delay before semantic search is available (lexical search works immediately while the model loads)

Build-Time vs Query-Time

Configuration Reference

[search]
# Enable semantic search (default: false)
semantic = true

# Custom GGUF model (overrides bundled BGE Micro v2)
# model_path = "./models/my-model.gguf"

When model_path is set, Oxidoc uses your model instead of the bundled one. See Custom Models for details.

Embedding Output Format

When semantic search is enabled, oxidoc build writes search-vectors.json to your output directory. This is a plain JSON file containing every page's embedding:

{
  "dimension": 384,
  "documents": [
    {
      "id": 0,
      "title": "Installation",
      "path": "/docs/installation",
      "snippet": "Install Oxidoc with a single command on Linux, macOS, or Windows...",
      "text": "The recommended way to install Oxidoc is the install script...",
      "headings": [
        { "title": "Install Script", "anchor": "install-script", "depth": 2, "offset": 0 },
        { "title": "GitHub Releases", "anchor": "github-releases", "depth": 2, "offset": 312 }
      ]
    }
  ],
  "vectors": [
    [0.0231, -0.0412, 0.0889, "... 384 floats total ..."]
  ]
}

Each entry in vectors corresponds to the document at the same index in documents. The vectors are 32-bit floats, one per dimension (384 for the default model).

Using Embeddings in Your Own RAG Pipeline

The search-vectors.json file is a portable artifact you can use outside of Oxidoc. After running oxidoc build, copy the file and feed it into any vector database or RAG pipeline:

import json
import numpy as np

with open("dist/search-vectors.json") as f:
    data = json.load(f)

vectors = np.array(data["vectors"], dtype=np.float32)
docs = data["documents"]

# Compute cosine similarity with a query embedding
query = your_model.encode("how do I configure search?")
similarities = vectors @ query / (np.linalg.norm(vectors, axis=1) * np.linalg.norm(query))

# Top 5 results
top_indices = np.argsort(similarities)[::-1][:5]
for idx in top_indices:
    print(f"{docs[idx]['title']}: {similarities[idx]:.4f}")

import json
import chromadb

with open("dist/search-vectors.json") as f:
    data = json.load(f)

client = chromadb.Client()
collection = client.create_collection("docs")

collection.add(
    ids=[str(d["id"]) for d in data["documents"]],
    embeddings=data["vectors"],
    documents=[d["text"] for d in data["documents"]],
    metadatas=[{"title": d["title"], "path": d["path"]} for d in data["documents"]],
)

# Query
results = collection.query(query_texts=["how to deploy"], n_results=5)

const data = JSON.parse(fs.readFileSync("dist/search-vectors.json", "utf-8"));

// Each vector is a Float32 array of `dimension` length
const { documents, vectors, dimension } = data;

// Feed into Pinecone, Weaviate, Qdrant, etc.
for (let i = 0; i < documents.length; i++) {
  await vectorDB.upsert({
    id: documents[i].path,
    values: vectors[i],
    metadata: {
      title: documents[i].title,
      snippet: documents[i].snippet,
    },
  });
}

What's Included Per Document

The text and headings fields give you everything needed to build section-level retrieval — split text by heading offsets to create chunks mapped to specific sections.