npm i @huggingface/transformers sqlite-vec better-sqlite3

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content'],
  compatibilityDate: '2025-07-15',

  nitro: {
    externals: {
      // Native .node binaries cannot be inlined into a bundle. Left to its
      // own devices, Nitro will try, and you get a build that succeeds and
      // a server that dies on first import.
      external: [
        '@huggingface/transformers',
        'onnxruntime-node',
        'sharp',
        'better-sqlite3',
        'sqlite-vec',
      ],
    },
  },

  runtimeConfig: {
    // Server-only. Both are absolute or root-relative paths/secrets, so they
    // must stay out of the public block.
    searchIndexPath: './.data/search/index.sqlite',
    modelCacheDir: './.cache/models',
    reindexToken: '',
  },
})

// shared/search.ts

// The model and its dimension count travel together. Change one and you must
// change the other, and you must rebuild the index — a vec0 column's width is
// baked into the table's DDL and mismatched query vectors are a hard error.
export const EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2'
export const EMBEDDING_DIMS = 384

export interface SearchHit {
  /** Page path plus heading anchor, e.g. /articles/2026-08/foo#chunking */
  url: string
  /** Page title */
  title: string
  /** Heading trail within the page, outermost first */
  headings: string[]
  /** Plain text, possibly with <mark> tags from FTS5's snippet() */
  snippet: string
  /** Fused score. Higher is better. Not a probability, not comparable across queries. */
  score: number
  /** Which retriever(s) surfaced this chunk. Useful for debugging relevance. */
  matched: Array<'vector' | 'keyword'>
}

export interface SearchResponse {
  query: string
  hits: SearchHit[]
  /** Milliseconds spent embedding the query, for the performance section below. */
  embedMs: number
}

// server/utils/embedder.ts
import { pipeline, env, type FeatureExtractionPipeline } from '@huggingface/transformers'
import { EMBEDDING_MODEL } from '#shared/search'

let pipelinePromise: Promise<FeatureExtractionPipeline> | null = null

export function getEmbedder(): Promise<FeatureExtractionPipeline> {
  if (!pipelinePromise) {
    // Must be set before the first pipeline() call — see below for why the
    // default location is a trap.
    env.cacheDir = useRuntimeConfig().modelCacheDir

    // NOT awaited. We cache the *promise*, so two requests arriving during a
    // cold start share one model load instead of racing to download 23 MB twice.
    pipelinePromise = pipeline('feature-extraction', EMBEDDING_MODEL, {
      // In Node the default dtype is fp32. Overriding to q8 takes this model
      // from ~90 MB to ~23 MB with a relevance cost you will not be able to
      // measure on prose.
      dtype: 'q8',
    })
  }
  return pipelinePromise
}

export async function embed(texts: string[]): Promise<Float32Array[]> {
  const extractor = await getEmbedder()

  // pooling: 'mean' collapses per-token vectors into one per input.
  // normalize: true gives unit-length vectors — see section 5 on why that
  // matters more than it looks like it does.
  const output = await extractor(texts, { pooling: 'mean', normalize: true })

  const [rows, dims] = output.dims as [number, number]

  return Array.from({ length: rows }, (_, i) =>
    // subarray() returns a VIEW onto the batch's shared buffer. Wrapping it in
    // a Float32Array constructor copies. Skip the copy and every vector you
    // store pins the entire batch in memory until all of them are released.
    new Float32Array(output.data.subarray(i * dims, (i + 1) * dims)),
  )
}

// server/utils/search-db.ts
import { mkdirSync } from 'node:fs'
import { dirname, resolve } from 'node:path'
import Database from 'better-sqlite3'
import * as sqliteVec from 'sqlite-vec'
import { EMBEDDING_DIMS } from '#shared/search'

let db: Database.Database | null = null

export function useSearchDb(): Database.Database {
  if (db) return db

  const file = resolve(useRuntimeConfig().searchIndexPath)
  mkdirSync(dirname(file), { recursive: true })

  db = new Database(file)

  // This is literally `db.loadExtension(pathToVec0)`. better-sqlite3 permits
  // extension loading unconditionally — there is no allowExtension option
  // here. (node:sqlite is the opposite: it needs { allowExtension: true } in
  // the constructor and cannot be talked into it afterwards.)
  sqliteVec.load(db)

  db.pragma('journal_mode = WAL')

  db.exec(`
    -- Plain table. Source of truth for text, and the join target after KNN.
    create table if not exists chunks (
      id       integer primary key,
      url      text    not null,
      path     text    not null,
      title    text    not null,
      headings text    not null,  -- JSON array
      content  text    not null
    );

    -- Keyword index. content='chunks' makes this an external content table:
    -- FTS5 stores only the index, not a second copy of the text.
    create virtual table if not exists chunks_fts using fts5(
      headings,
      content,
      content='chunks',
      content_rowid='id',
      tokenize='porter unicode61'
    );

    -- Vector index. No primary key declared, so rowid stays available and we
    -- keep it identical to chunks.id. Declaring any PK on a vec0 table makes
    -- it WITHOUT ROWID and 'select rowid' starts failing.
    create virtual table if not exists vec_chunks using vec0(
      embedding float[${EMBEDDING_DIMS}] distance_metric=cosine
    );
  `)

  return db
}

// server/utils/chunker.ts
import type { H3Event } from 'h3'

export interface Chunk {
  url: string
  path: string
  title: string
  headings: string[]
  content: string
}

// all-MiniLM-L6-v2 truncates at 256 tokens. ~4 chars per token for English
// prose gives a soft budget around 1000 characters; the overlap keeps a
// sentence that straddles a boundary retrievable from both sides.
const MAX_CHARS = 1000
const OVERLAP_CHARS = 150

export async function buildChunks(event: H3Event): Promise<Chunk[]> {
  const sections = await queryCollectionSearchSections(event, 'content', {
    // Code blocks are noise for a sentence-embedding model — they eat the
    // token budget and push the prose that explains them out of the window.
    // They stay searchable via FTS5 if you'd rather keep them; see the note.
    ignoredTags: ['pre', 'code'],
  })

  const chunks: Chunk[] = []

  for (const section of sections) {
    const text = section.content?.trim()
    if (!text || text.length < 40) continue // headings with no body under them

    // section.id is `/path` for the h1 and `/path#anchor` for everything else.
    const [path] = section.id.split('#')

    for (const part of splitWithOverlap(text, MAX_CHARS, OVERLAP_CHARS)) {
      chunks.push({
        url: section.id,
        path: path!,
        title: section.titles[0] ?? section.title,
        // The heading trail. Prepending it to the embedded text is the cheap
        // trick that makes a chunk called "Gotchas" retrievable, because on
        // its own that word means nothing.
        headings: section.titles,
        content: part,
      })
    }
  }

  return chunks
}

function splitWithOverlap(text: string, max: number, overlap: number): string[] {
  if (text.length <= max) return [text]

  const parts: string[] = []
  let start = 0

  while (start < text.length) {
    let end = Math.min(start + max, text.length)

    if (end < text.length) {
      // Prefer a sentence boundary, fall back to a space, then to a hard cut.
      const window = text.slice(start, end)
      const boundary = Math.max(
        window.lastIndexOf('. '),
        window.lastIndexOf('? '),
        window.lastIndexOf('! '),
      )
      if (boundary > max * 0.5) end = start + boundary + 1
      else {
        const space = window.lastIndexOf(' ')
        if (space > max * 0.5) end = start + space
      }
    }

    parts.push(text.slice(start, end).trim())
    if (end >= text.length) break
    start = Math.max(end - overlap, start + 1)
  }

  return parts
}

// server/api/search/reindex.post.ts
import { buildChunks, type Chunk } from '../../utils/chunker'
import { embed } from '../../utils/embedder'
import { useSearchDb } from '../../utils/search-db'

const BATCH_SIZE = 32

export default defineEventHandler(async (event) => {
  const { reindexToken } = useRuntimeConfig(event)

  // No token configured means the endpoint is off, not open. An unauthenticated
  // reindex is a trivially abusable CPU sink.
  if (!reindexToken || getHeader(event, 'authorization') !== `Bearer ${reindexToken}`) {
    throw createError({ statusCode: 401, statusMessage: 'Unauthorized' })
  }

  const started = Date.now()
  const db = useSearchDb()
  const chunks = await buildChunks(event)

  const insertChunk = db.prepare(`
    insert into chunks (id, url, path, title, headings, content)
    values (?, ?, ?, ?, ?, ?)
  `)
  const insertFts = db.prepare(`
    insert into chunks_fts (rowid, headings, content) values (?, ?, ?)
  `)
  const insertVec = db.prepare(`
    insert into vec_chunks (rowid, embedding) values (?, ?)
  `)

  const writeBatch = db.transaction((rows: Array<{ chunk: Chunk, id: number, vector: Float32Array }>) => {
    for (const { chunk, id, vector } of rows) {
      const headings = JSON.stringify(chunk.headings)
      insertChunk.run(id, chunk.url, chunk.path, chunk.title, headings, chunk.content)
      insertFts.run(id, chunk.headings.join(' '), chunk.content)
      // better-sqlite3 binds any TypedArray as a BLOB, and vec0 reads a
      // float32 BLOB directly. Pass the Float32Array itself — NOT .buffer,
      // which is wrong the moment the view has a non-zero byteOffset.
      insertVec.run(id, vector)
    }
  })

  // Wipe first. Three different incantations, which is not an accident:
  db.transaction(() => {
    db.exec('delete from chunks')
    // External content FTS5 tables reject a plain DELETE. 'delete-all' is the
    // documented command and the error you get without it is not helpful.
    db.exec(`insert into chunks_fts (chunks_fts) values ('delete-all')`)
    // vec0 DELETE only became reliable in sqlite-vec 0.1.7 (and 0.1.9 fixed a
    // further bug with metadata TEXT over 12 chars). On anything older, drop
    // and recreate the table instead.
    db.exec('delete from vec_chunks')
  })()

  let id = 0
  for (let i = 0; i < chunks.length; i += BATCH_SIZE) {
    const batch = chunks.slice(i, i + BATCH_SIZE)

    // Embed the heading trail together with the body — see section 5.
    const vectors = await embed(
      batch.map(c => `${c.headings.join(' > ')}\n\n${c.content}`),
    )

    writeBatch(batch.map((chunk, j) => ({ chunk, id: ++id, vector: vectors[j]! })))
  }

  return {
    chunks: chunks.length,
    ms: Date.now() - started,
  }
})

curl -fsS -X POST https://example.com/api/search/reindex \
  -H "Authorization: Bearer $NUXT_REINDEX_TOKEN"

// server/utils/retrieval.ts
import type { Database } from 'better-sqlite3'

/** How many candidates each retriever contributes before fusion. */
const CANDIDATES = 30

export function vectorCandidates(db: Database, queryVector: Float32Array, k = CANDIDATES) {
  return db.prepare(`
    select rowid as id, distance
    from vec_chunks
    where embedding match ?
      and k = ?
    order by distance
  `).all(queryVector, k) as Array<{ id: number, distance: number }>
}

export function keywordCandidates(db: Database, query: string, limit = CANDIDATES) {
  const match = toFtsQuery(query)
  if (!match) return []

  return db.prepare(`
    select rowid as id, rank
    from chunks_fts
    where chunks_fts match ?
    order by rank
    limit ?
  `).all(match, limit) as Array<{ id: number, rank: number }>
}

/**
 * FTS5's MATCH argument is a query language, not a string. A user typing
 * `nuxt-content` or `"` produces a syntax error, which surfaces as a 500 on
 * your search endpoint. Quote every token, escape embedded quotes, and add a
 * prefix wildcard to the last one so results appear while they're still typing.
 */
function toFtsQuery(input: string): string {
  const tokens = input
    .toLowerCase()
    .split(/[^\p{L}\p{N}_]+/u)
    .filter(t => t.length > 1)

  if (!tokens.length) return ''

  return tokens
    .map((t, i) => {
      const quoted = `"${t.replace(/"/g, '""')}"`
      return i === tokens.length - 1 ? `${quoted}*` : quoted
    })
    .join(' OR ')
}

// server/utils/fuse.ts

/**
 * Reciprocal Rank Fusion. Each retriever contributes 1 / (K + rank) per
 * document; the sum is the final score.
 *
 * The reason this and not a weighted average of the raw scores: cosine
 * distance (0..2, lower is better) and BM25 rank (unbounded negative, lower is
 * better) are not on the same scale, are not on the same scale *as each other
 * across different queries*, and any normalisation you invent will be tuned to
 * whatever three queries you happened to test. RRF throws the magnitudes away
 * and keeps only the ordering, which is the part that's actually comparable.
 *
 * K = 60 comes from the original Cormack et al. paper and is the number
 * everyone uses. Larger K flattens the contribution of top ranks; smaller K
 * lets a single retriever's #1 dominate.
 */
const K = 60

export interface Fused {
  id: number
  score: number
  matched: Array<'vector' | 'keyword'>
}

export function reciprocalRankFusion(
  vector: Array<{ id: number }>,
  keyword: Array<{ id: number }>,
  weights: { vector: number, keyword: number } = { vector: 1, keyword: 1 },
): Fused[] {
  const scores = new Map<number, Fused>()

  const contribute = (
    rows: Array<{ id: number }>,
    source: 'vector' | 'keyword',
    weight: number,
  ) => {
    rows.forEach((row, index) => {
      const existing = scores.get(row.id) ?? { id: row.id, score: 0, matched: [] }
      existing.score += weight / (K + index + 1)
      existing.matched.push(source)
      scores.set(row.id, existing)
    })
  }

  contribute(vector, 'vector', weights.vector)
  contribute(keyword, 'keyword', weights.keyword)

  return [...scores.values()].sort((a, b) => b.score - a.score)
}

// server/api/search.get.ts
import { embed } from '../utils/embedder'
import { useSearchDb } from '../utils/search-db'
import { vectorCandidates, keywordCandidates } from '../utils/retrieval'
import { reciprocalRankFusion } from '../utils/fuse'
import type { SearchHit, SearchResponse } from '#shared/search'

export default defineCachedEventHandler(async (event): Promise<SearchResponse> => {
  const query = (getQuery(event).q as string | undefined)?.trim() ?? ''
  const limit = Math.min(Number(getQuery(event).limit) || 10, 25)

  if (query.length < 2) return { query, hits: [], embedMs: 0 }

  const db = useSearchDb()

  const t0 = performance.now()
  const [queryVector] = await embed([query])
  const embedMs = Math.round(performance.now() - t0)

  const vector = vectorCandidates(db, queryVector!)
  const keyword = keywordCandidates(db, query)

  const fused = reciprocalRankFusion(vector, keyword).slice(0, limit)
  if (!fused.length) return { query, hits: [], embedMs }

  const ids = fused.map(f => f.id)
  const placeholders = ids.map(() => '?').join(',')

  const rows = db.prepare(`
    select
      c.id, c.url, c.title, c.headings, c.content,
      -- snippet() only produces marks for rows the FTS query matched; for
      -- vector-only hits it returns the leading text, which is what we want
      -- as a fallback anyway.
      snippet(chunks_fts, 1, '<mark>', '</mark>', '…', 20) as snippet
    from chunks c
    join chunks_fts on chunks_fts.rowid = c.id
    where c.id in (${placeholders})
  `).all(...ids) as Array<Record<string, string | number>>

  const byId = new Map(rows.map(r => [r.id as number, r]))

  const hits: SearchHit[] = fused.flatMap((f) => {
    const row = byId.get(f.id)
    if (!row) return []
    return [{
      url: row.url as string,
      title: row.title as string,
      headings: JSON.parse(row.headings as string) as string[],
      snippet: (row.snippet as string) || (row.content as string).slice(0, 200),
      score: f.score,
      matched: [...new Set(f.matched)],
    }]
  })

  return { query, hits, embedMs }
}, {
  // Query strings repeat far more than you'd think, and the expensive half of
  // this handler is deterministic given the same query and index.
  maxAge: 60 * 10,
  name: 'search',
  getKey: event => `${getQuery(event).q}:${getQuery(event).limit ?? 10}`,
})

// app/composables/useSemanticSearch.ts
import type { SearchResponse } from '#shared/search'

export function useSemanticSearch() {
  const query = ref('')
  const pending = ref(false)
  const results = shallowRef<SearchResponse | null>(null)

  let timer: ReturnType<typeof setTimeout> | undefined
  let controller: AbortController | undefined

  watch(query, (value) => {
    clearTimeout(timer)
    // Every keystroke is a CPU-bound embed on the server. Debounce hard —
    // this is not a database index lookup and it should not be treated like one.
    timer = setTimeout(async () => {
      const q = value.trim()
      if (q.length < 2) {
        results.value = null
        return
      }

      // Cancel the in-flight request so a slow early query cannot land after
      // a fast later one and overwrite it.
      controller?.abort()
      controller = new AbortController()

      pending.value = true
      try {
        results.value = await $fetch<SearchResponse>('/api/search', {
          query: { q },
          signal: controller.signal,
        })
      }
      catch (error) {
        if ((error as Error)?.name !== 'AbortError') throw error
      }
      finally {
        pending.value = false
      }
    }, 250)
  })

  onScopeDispose(() => {
    clearTimeout(timer)
    controller?.abort()
  })

  return { query, pending, results }
}

<!-- app/components/SearchBox.vue -->
<script setup lang="ts">
const { query, pending, results } = useSemanticSearch()
</script>

<template>
  <div class="relative">
    <input
      v-model="query"
      type="search"
      placeholder="Search — try a question, not a keyword"
      class="w-full rounded-xl border border-white/10 bg-slate-900/60 px-4 py-3 text-sm outline-none focus:border-emerald-400/60"
    >

    <p v-if="pending" class="mt-2 text-xs text-slate-400">
      Searching…
    </p>

    <ul v-else-if="results?.hits.length" class="mt-4 space-y-3">
      <li v-for="hit in results.hits" :key="hit.url">
        <NuxtLink :to="hit.url" class="block rounded-xl bg-white/5 p-4 hover:bg-white/10">
          <p class="text-xs text-slate-400">
            {{ hit.headings.join(' › ') }}
          </p>
          <p class="font-medium">
            {{ hit.title }}
          </p>
          <!-- snippet() emits <mark> tags. This is server-generated from your
               own indexed content, not user input — but if you ever index
               user-submitted text, sanitise before you do this. -->
          <p class="mt-1 text-sm text-slate-300" v-html="hit.snippet" />
          <span
            v-if="hit.matched.length === 2"
            class="mt-2 inline-block rounded bg-emerald-400/10 px-2 py-0.5 text-[11px] text-emerald-300"
          >keyword + meaning</span>
        </NuxtLink>
      </li>
    </ul>

    <p v-else-if="results" class="mt-4 text-sm text-slate-400">
      Nothing found for “{{ results.query }}”.
    </p>
  </div>
</template>

// server/plugins/warm-search.ts
import { getEmbedder } from '../utils/embedder'

export default defineNitroPlugin(() => {
  // Dev reloads constantly; warming on every restart is just noise.
  if (import.meta.dev) return

  // Not awaited — a plugin that blocks here blocks the whole server's boot.
  getEmbedder()
    .then(() => console.log('[search] embedder ready'))
    .catch(error => console.error('[search] embedder warmup failed', error))
})

# Debian slim, NOT alpine. sqlite-vec publishes no musl binary; onnxruntime-node
# and better-sqlite3 are also glibc-only in their prebuilt form.
FROM node:22-bookworm-slim AS build
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# Bake the model into the image. Without this, the first cold start in
# production downloads 23 MB — and does it again on every new container.
RUN node -e "\
  const { pipeline, env } = require('@huggingface/transformers'); \
  env.cacheDir = '/app/.cache/models'; \
  pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { dtype: 'q8' }) \
    .then(() => console.log('model cached')); \
"

FROM node:22-bookworm-slim
WORKDIR /app
ENV NODE_ENV=production
ENV NUXT_MODEL_CACHE_DIR=/app/.cache/models
ENV NUXT_SEARCH_INDEX_PATH=/data/search/index.sqlite

# node_modules ships too — the native modules are external to the bundle and
# cannot be inlined. See section 1.
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/.output ./.output
COPY --from=build /app/.cache/models ./.cache/models

# The index lives on a volume so a redeploy doesn't discard it. You still want
# to reindex after deploy — content changed — but a container restart shouldn't
# leave search dead until someone notices.
VOLUME ["/data"]

EXPOSE 3000
CMD ["node", ".output/server/index.mjs"]