# How to Use the LLM Wiki API for Hybrid Search: A Complete Guide

> Learn to use the LLM Wiki API for hybrid search. Combine BM25 keyword scoring and vector search via LanceDB with this complete guide. Access the local HTTP API today.

- Repository: [nash_su/llm_wiki](https://github.com/nashsu/llm_wiki)
- Tags: how-to-guide
- Published: 2026-09-13

---

**LLM Wiki exposes a local HTTP API at `http://127.0.0.1:19828` that performs hybrid search by combining BM25 keyword scoring, vector similarity search via LanceDB, and optional graph-based link expansion through a single POST endpoint.**

The open-source **LLM Wiki** repository (`nashsu/llm_wiki`) provides a self-hosted knowledge base with a built-in hybrid search engine. This architecture enables external scripts, AI agents, and frontend applications to execute complex retrieval-augmented generation (RAG) workflows without managing separate search infrastructure.

## Understanding the Hybrid Search Architecture

When you send a request to the LLM Wiki API, the query is processed through a three-stage pipeline implemented in the Rust backend. The entry point is the `search_project` command located in [[`src-tauri/src/commands/search.rs`](https://github.com/nashsu/llm_wiki/blob/main/src-tauri/src/commands/search.rs)](https://github.com/nashsu/llm_wiki/blob/main/src-tauri/src/commands/search.rs#L107-L127), which is exposed via the Tauri bridge.

The system merges results from three distinct retrieval strategies:

- **Lexical matching** using BM25-style heuristics with title and filename bonuses
- **Semantic similarity** using vector embeddings stored in LanceDB
- **Graph expansion** adding one-hop Wikipedia-style link context

This multi-modal approach ensures high recall for exact keyword matches while maintaining semantic understanding for conceptually related content.

## Making API Requests to the LLM Wiki Hybrid Search Endpoint

The primary endpoint is `POST /api/v1/projects/{id}/search`. You must replace `{id}` with your project identifier. The server expects a JSON payload containing your query string and optional configuration parameters.

### cURL Example

Use this command to test the endpoint from any terminal:

```bash
curl -X POST http://127.0.0.1:19828/api/v1/projects/12345/search \
  -H "Content-Type: application/json" \
  -d '{
        "query": "how to reset my password",
        "topK": 10,
        "includeContent": false,
        "queryEmbedding": null,
        "embeddingConfig": null
      }'

```

### Python Implementation

For production Python applications, use the `requests` library to parse the `ProjectSearchResponse`:

```python
import requests

url = "http://127.0.0.1:19828/api/v1/projects/12345/search"
payload = {
    "query": "how to reset my password",
    "topK": 10,
    "includeContent": False,
    "queryEmbedding": None,
    "embeddingConfig": None      # omit or supply an embedding config to enable vector search

}
resp = requests.post(url, json=payload)
data = resp.json()

print("Search mode:", data["mode"])
for hit in data["results"]:
    print(f"- {hit['title']} ({hit['path']}) → score {hit['score']:.2f}")

```

### TypeScript Frontend Integration

If you are building within the LLM Wiki ecosystem, use the provided helper in [[`src/lib/search.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/search.ts)](https://github.com/nashsu/llm_wiki/blob/main/src/lib/search.ts):

```typescript
import { searchWiki } from "@/lib/search";

const results = await searchWiki("/path/to/project", "how to reset my password");
console.log(results);

```

## How Hybrid Ranking Works Internally

The LLM Wiki API implements a sophisticated ranking pipeline that processes your query through sequential retrieval stages before returning fused results.

### Stage 1: Keyword Retrieval with BM25

The query string is first tokenized using the `tokenize_query` function in [[`src/lib/search.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/search.ts)](https://github.com/nashsu/llm_wiki/blob/main/src/lib/search.ts#L38-L60). Each markdown file in the project's `wiki/` folder receives a BM25-style relevance score that includes:

- **Title-match bonus**: Higher weight for terms appearing in document titles
- **Filename exact bonus**: Exact matches against file paths
- **Phrase-in-content weighting**: Positional scoring for query terms within body text

Results are sorted via `token_rank` and passed to the next stage.

### Stage 2: Vector Retrieval and RRF Fusion

If an **embedding configuration** is provided (or server-side defaults are enabled), the system performs a parallel vector search. The `embedding_fetch` endpoint generates query embeddings, and `search_by_embedding` (lines 331-350 in [`search.rs`](https://github.com/nashsu/llm_wiki/blob/main/search.rs)) queries the LanceDB vector store for nearest neighbors.

The system merges keyword and vector results using **Reciprocal Rank Fusion** (`apply_rrf_scores`), which balances the ranked positions from both retrieval methods without requiring score normalization.

### Stage 3: Graph Link Expansion

After fusion, the `blend_graph_results` function performs a lightweight graph pass that adds one-hop Wikipedia-style links to the result set. This respects the configured `MIN_GRAPH_RESULT_RATIO` and `MAX_GRAPH_RESULT_RATIO` constants, ensuring graph expansion supplements rather than overwhelms the primary search results.

## Interpreting the Search Response

The API returns a `ProjectSearchResponse` object containing:

- **`mode`**: Indicates which retrieval methods activated—`"hybrid"` when both token and vector sources contribute, otherwise `"keyword"` or `"vector"` (see [`search_mode`](https://github.com/nashsu/llm_wiki/blob/main/src-tauri/src/commands/search.rs#L764-L779))
- **`token_hits`**, **`vector_hits`**, **`graph_hits`**: Integer counts for each retrieval type
- **`results`**: An array of hit objects containing:
  - `path`: File path relative to the wiki directory
  - `title`: Document title
  - `snippet`: Text excerpt around matching terms
  - `score`: Final fused relevance score
  - `vectorScore`: Raw similarity score when applicable
  - `images`: Array of embedded image references

This structured response allows clients to filter or rerank results based on confidence thresholds or specific hit type requirements.

## Summary

- **LLM Wiki** provides a local HTTP API at `http://127.0.0.1:19828` for hybrid search operations
- The **`/api/v1/projects/{id}/search`** endpoint accepts POST requests and routes through the `search_project` Rust command
- Search combines **BM25 keyword retrieval**, **LanceDB vector similarity**, and **graph link expansion** through Reciprocal Rank Fusion
- Configuration is controlled via the `embeddingConfig` parameter and server-side constants like `MIN_GRAPH_RESULT_RATIO`
- Response objects include detailed metadata about which retrieval modes contributed to each result

## Frequently Asked Questions

### What is the default port for the LLM Wiki API?

The local HTTP server binds to port **19828** by default, making the base URL `http://127.0.0.1:19828`. This is defined in the API server implementation within [`src-tauri/src/api_server.rs`](https://github.com/nashsu/llm_wiki/blob/main/src-tauri/src/api_server.rs).

### How does LLM Wiki combine keyword and vector search results?

The system uses **Reciprocal Rank Fusion** (`apply_rrf_scores`) to merge ranked lists from the BM25 keyword stage and the LanceDB vector stage. This algorithm weights results by their inverse rank positions, ensuring high-ranked items from either method surface in the final output without requiring score calibration between the different retrieval modalities.

### Can I disable vector search and use only keyword matching?

Yes. Set the `queryEmbedding` field to `null` and omit the `embeddingConfig` parameter in your request payload. When no embedding configuration is present, the `search_project` command skips the `search_by_embedding` stage and returns results flagged with mode `"keyword"` rather than `"hybrid"`.

### What embedding database does LLM Wiki use for vector search?

LLM Wiki uses **LanceDB** as its vector store, implemented in [`src-tauri/src/commands/vectorstore.rs`](https://github.com/nashsu/llm_wiki/blob/main/src-tauri/src/commands/vectorstore.rs). The hybrid search system queries this database during the optional vector retrieval stage to perform nearest-neighbor searches against pre-computed document embeddings.