Knowhere Self-Hosted

English | 中文

Knowhere Self-Hosted packages Knowhere for self-hosted deployments. If you want to use the SaaS/API version, see Ontos-AI/knowhere.

Requirements

• Docker and Docker Compose.
• A MinerU API key for the initial parsing of PDF documents (not required if you run a local MinerU instance — see Local MinerU mode).
• LLM provider API key: DeepSeek or Alibaba Cloud Model Studio DashScope.

For now, our setup uses MinerU as the default PDF parser. If you customize the parsing pipeline, your own parser can also work as long as it produces Markdown (.md) files for Knowhere to process. If you'd like to contribute support for additional PDF parsers, feel free to submit a pull request.

1. Prepare API Keys

• MinerU
• DeepSeek
• Alibaba Cloud Model Studio DashScope

2. Configure .env

Create a new .env file with only the values you need.

For DeepSeek:

MINERU_API_KEYS=your-mineru-api-key
DS_KEY=your-deepseek-api-key

For Alibaba Cloud Model Studio DashScope:

MINERU_API_KEYS=your-mineru-api-key
ALI_API_KEYS=your-dashscope-api-key
NORMOL_MODEL=qwen-plus
HIERARCHY_LLM_MODEL=qwen-plus
IMAGE_MODEL=qwen3.6-flash
IMAGE_MODEL_MAX=qwen3.6-flash

MINERU_API_KEYS and ALI_API_KEYS support multiple keys separated by commas. Multiple keys are optional; they form a key pool so Knowhere can rotate requests across keys when one key reaches provider quota or rate limits.

MINERU_API_KEYS=mineru-key-1,mineru-key-2
ALI_API_KEYS=dashscope-key-1,dashscope-key-2

For local access, no other settings are required. Host ports bind to 127.0.0.1 by default.

For external access through a local reverse proxy, keep the default binds and set DASHBOARD_PUBLIC_URL to the exact URL users open in their browser:

DASHBOARD_PUBLIC_URL=https://knowhere.example.com

If DASHBOARD_PUBLIC_URL does not match the browser URL, login or signup may fail.

If users need to connect directly to the host ports from another machine, also expose only the required public services:

DASHBOARD_HOST_BIND=0.0.0.0
API_HOST_BIND=0.0.0.0

If pulling the default image from GHCR is slow or unavailable, use the Aliyun Docker registry:

KNOWHERE_IMAGE=knowhere-registry.cn-shenzhen.cr.aliyuncs.com/knowhere/knowhere:latest

Self-hosted deployments send anonymous product telemetry by default (TELEMETRY_ENABLED=true). It uses a random installation id and aggregate metrics only — not prompts, filenames, user identity, or request bodies. To opt out, set TELEMETRY_ENABLED=false. See Anonymous product telemetry for the event catalog, privacy bounds, and property tables.

Local MinerU mode

To run Knowhere against a self-hosted MinerU instance instead of mineru.net, set the following in .env:

MINERU_LOCAL_MODE=true
MINERU_URL=http://host.docker.internal:8000

MINERU_API_KEYS is not required in this mode. The container reaches your local MinerU via host.docker.internal, which compose.yaml maps to the Docker host on Linux, Docker Desktop, and OrbStack. See Local MinerU mode in the configuration reference for parameter tuning, shard concurrency, and timeouts.

3. Start Knowhere

docker compose up -d

Open the Dashboard:

http://localhost:3000/login

API health check:

http://localhost:5005/health

API Usage

Use an official SDK to call the API:

• Node.js SDK: Ontos-AI/knowhere-node-sdk
• Python SDK: Ontos-AI/knowhere-python-sdk

Common Commands

Check service status:

docker compose ps

View application logs:

docker compose logs -f app

Stop the stack:

docker compose down

Update images and restart:

docker compose pull
docker compose up -d

Database data and uploaded files remain in Docker volumes after docker compose down.

More Configuration

There are more configurations like model choices, storage, webhooks, database, and Redis settings are documented in docs/configuration.md.