Scenario combo Β· 2 tools Β· recorded 2026-09-01

Combo: Local Knowledge Base Q&A (ollama + MaxKB) βœ“ Verified

You want to turn your notes/PDFs/company docs into a private knowledge base you can ask questions against, but do not know which tools to use β€” one bundle: model runtime + knowledge base Q&A console, China-network adapted.

← All combos πŸ€– Agent-readable version Download install script ↓

Scenario

You have piled up notes, PDFs and company documents and want to "ask your own material" instead of searching the whole web: feed the documents in, ask in natural language, and get answers based on your own content. The tutorials you find contradict each other: some push cloud platforms (your data leaves the machine), some tell you to assemble a pile of components (vector DB + chunking + embedding all hand-built), some trail off halfway. This combo gives you a path that runs in about 30 minutes: ollama runs the local model (data stays on your machine) and MaxKB handles "upload documents β†’ auto chunk + vectorize β†’ answer from the documents" with a built-in web UI. After the install you get a knowledge base Q&A console at http://localhost:8080 β€” drag a document in and ask.

Combo members

ollama: model download and runtime base (core)

  • Download: official https://ollama.com/download (install.sh / Windows installer / macOS dmg); Linux binary = GitHub Release asset ollama-linux-amd64.tar.zst (use the gh-proxy prefix in China, measured 2026-08-29)
  • Version: >= 0.33.2 (measured 2026-08-29; MaxKB connects via the OpenAI-compatible API, so it is not version-sensitive)
  • Install: see "Walkthrough step 1" (reuses the measured path in site docs)

MaxKB: knowledge base Q&A console (core)

  • Download: official Docker image 1panel/maxkb (Docker Hub); China accelerator prefix docker.m.daocloud.io/1panel/maxkb (pull measured 2026-09-01)
  • Version: v2.10.5-lts (released 2026-08-06, latest tag); needs Docker (Compose optional); image 4.62GB (measured via daocloud 2026-09-01)
  • Install: see "Walkthrough step 2"

Solution overview

Two tools, each owning one stage:

ToolOwns whatWhy this one
ollamamodel download, runtime, API (base)one command runs local models with a built-in OpenAI-compatible API; this repo already measured the China path (gh-proxy binary + ModelScope model import)
MaxKBknowledge base Q&A console: document parsing/chunking/vectorizing/retrieval/answering (core)Chinese project (1Panel team, GitHub 22k+ stars), one Docker command, bundled Postgres + vector capability, supports ollama out of the box; Chinese UI and docs

Alternatives: AnythingLLM (desktop app, good if you are not familiar with Docker; installers 400-860MB) / Dify (heavy, oriented at building apps) / coze (cloud, data leaves the country). CLI-only users can use just ollama (ollama run for chat, but no knowledge base). Install order follows dependencies: ollama first (model base; MaxKB needs its API when you configure the model source) β†’ MaxKB next (Docker container; point the model source at ollama in the admin console).

Quick start (skip the walkthrough)

The one-click script is auto-generated from this document (rendered at pages/combos/combo-local-rag.sh), adapted for official download sources + domestic mirrors; run it line by line:
bash pages/combos/combo-local-rag.sh
  • After the install you get: ollama service (port 11434) + knowledge base Q&A console (http://localhost:8080).
  • Estimated time: 10-20 minutes. Biggest blocker = first MaxKB image pull (4.62GB, daocloud accelerator, measured 2026-09-01); model download is extra (4-70GB depending on model size β€” pull a small model first to verify the chain).
  • Prerequisites: RAM >= 8GB (16GB recommended); disk >= 10GB free; Docker (the WSL dockerd path is already measured in this repo).
Want to understand what each step does and how to recover from a broken install β†’ see "Walkthrough". If the one-click script fails β†’ run the walkthrough manually to locate the problem.

Walkthrough

Step 1: Install ollama (model base; everything depends on it)

ollama is the foundation of the whole stack: it manages model files (default ~/.ollama/models) and MaxKB uses its API (port 11434) for generation and embedding. The installer downloads the official script/binary and registers a background service; GitHub direct connections are slow in China, so use the gh-proxy prefix.

curl -fsSL https://gh-proxy.com/https://github.com/ollama/ollama/releases/latest/download/install.sh | sh
# or manual: download the tar.zst and extract (needs tar --zstd or the zstd tool)
curl -sL -o /tmp/ollama.tar.zst https://gh-proxy.com/https://github.com/ollama/ollama/releases/latest/download/ollama-linux-amd64.tar.zst
mkdir -p /tmp/ollama-bin && tar --zstd -xf /tmp/ollama.tar.zst -C /tmp/ollama-bin
/tmp/ollama-bin/bin/ollama --version

Expected output: ollama version 0.33.2 (or newer) How to confirm:

  • ollama --version prints a version number;
  • curl http://localhost:11434/api/version returns {"version":"0.33.2"}.

If stuck:

  • Download timeout/failure β†’ use the manual tar.zst path with the gh-proxy prefix (measured OK 2026-08-29).
  • tar --zstd errors β†’ sudo apt install -y zstd and retry.
  • Service did not start β†’ run ollama serve in the foreground to see logs; port taken β†’ OLLAMA_HOST=127.0.0.1:11435 ollama serve to change the port (update the MaxKB endpoint to match).
note: model downloads default to the official ollama registry (may time out in China); alternative = download the GGUF from ModelScope and import with ollama create (measured: qwen2.5-0.5b 491MB in 58.5s + create success + CPU smoke, evidence local repro log 2026-08-29).

Step 2: Install MaxKB (knowledge base Q&A console)

MaxKB is one Docker container that includes everything: bundled Postgres (data persistence), document parsing, vectorization, retrieval and generation. The official command mounts the data directory to ~/.maxkb, so removing the container does not lose data. When direct Docker Hub pulls fail in China, prefix the image name with docker.m.daocloud.io/ (measured pullable on 2026-09-01).

# China network: use the daocloud accelerator prefix (pull measured 2026-09-01)
docker run -d --name=maxkb --restart=always -p 8080:8080 \
-v ~/.maxkb:/opt/maxkb \
docker.m.daocloud.io/1panel/maxkb:latest
# Official (when Docker Hub is directly reachable)
# docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb

Expected output: container maxkb starts; http://localhost:8080 shows the login page in the browser How to confirm:

  • docker ps shows maxkb Up (first start initializes for 1-3 minutes; docker logs maxkb shows progress);
  • the browser shows the login page at http://localhost:8080 β†’ default account admin / MaxKB@123.. (change the password after first login).

If stuck:

  • Image pull fails β†’ switch to the accelerator prefix (daocloud); if it still fails, see the official offline install docs https://maxkb.cn/docs/v2/installation/offline_installtion/.
  • Port 8080 taken β†’ use -p 8081:8080 and visit the new port.
  • Login page will not open β†’ docker logs maxkb --tail 50 to see initialization errors; wait 1-3 minutes after a container restart.

Step 3: Connect MaxKB to ollama (the core link-up)

MaxKB ships without a model; point it at local ollama (the model stays on your machine). This step happens in the web UI β€” no commands needed.

  1. Log in to MaxKB (admin / MaxKB@123..) β†’ left sidebar "Model settings" β†’ "Model providers" β†’ pick Ollama;
  2. API base URL: http://host.docker.internal:11434 (the fixed host address for containers; if ollama runs directly on Linux, use http://127.0.0.1:11434);
  3. Pick an already-pulled model (e.g. qwen2.5:0.5b) and save;
  4. Left sidebar "Knowledge bases" β†’ create β†’ upload a document (PDF/Word/Markdown etc.) β†’ wait for parsing;
  5. Left sidebar "Applications" β†’ create an app β†’ select the model + link the knowledge base β†’ start asking.

Expected output: asking "what is XX in this document" is answered based on the document content If stuck:

  • Cannot reach ollama β†’ first confirm curl http://127.0.0.1:11434/api/version on the host; host.docker.internal requires Docker support (measured OK on WSL dockerd; older versions need --add-host=host.docker.internal:host-gateway).
  • Model list empty β†’ pull on the host first: ollama pull qwen2.5:0.5b (small model to verify the chain, or import a ModelScope GGUF).
  • Answers are not based on the document β†’ check three things in order (measured pitfalls 2026-09-01): β‘  the KB retrieval similarity threshold is too high β€” for local text2vec Chinese matching use similarity <= 0.2 (0.6 returns empty retrieval); β‘‘ the app's prompt must contain the {data} placeholder, otherwise retrieved paragraphs are not injected into the prompt and the model fabricates answers; β‘’ after editing app settings you must re-publish β€” chat reads the published snapshot (old config stays in effect).

Daily use

Start & entry points

  • ollama: service stays resident (ollama serve or system service), API at http://localhost:11434;
  • MaxKB: docker start maxkb, entry at http://localhost:8080.

Common operations

  • Add documents: MaxKB β†’ Knowledge bases β†’ upload (PDF/Word/Markdown/Excel/web pages etc.);
  • Switch models: MaxKB β†’ Model settings β†’ Providers β†’ Ollama β†’ change the model name (pull it on the host first);
  • Check status: docker logs maxkb --tail 20; ollama ps shows the currently loaded model.

Data & directories

  • MaxKB data: ~/.maxkb/ (container /opt/maxkb, includes Postgres data β€” back up this directory);
  • ollama models: ~/.ollama/models/ (OLLAMA_MODELS can point to a large partition).

Uninstall and cleanup

Uninstall in reverse install order:

docker rm -f maxkb
# data directory (knowledge base documents and config; gone for good)
rm -rf ~/.maxkb
# ollama if no longer needed: remove models + stop the service
ollama rm qwen2.5:0.5b 2>/dev/null

Expected output: container gone, directory cleaned up

note: ~/.maxkb is the knowledge base data itself β€” only delete it after confirming you no longer need it.

Install order

  1. ollama first (base) β€” smoke test with ollama --version, then pull a model (this step most often stalls on China networks; see step 1 "if stuck").
  2. MaxKB next (console) β€” start the Docker container (default port 8080), then in the admin console: Model settings β†’ pick ollama as provider β†’ fill http://host.docker.internal:11434 β†’ choose a model β†’ create a knowledge base β†’ upload documents β†’ ask questions.

The "why + commands + how to confirm + what to do if stuck" for each step is in the "Walkthrough".

Dependency warnings

  • Versions: ollama >= 0.33.2 (measured); MaxKB v2.10.5-lts (latest tag); Docker >= 20.10 (Compose optional).
  • Environment: RAM >= 8GB (16GB recommended when model loading + vectorization run together); disk: MaxKB image 4.62GB (measured) + models 4-70GB; ports 11434 (ollama) / 8080 (MaxKB).
  • Environment (measured pitfall): snap/apt ollama listens on 127.0.0.1:11434 only by default β€” bridge containers get connection refused (measured 2026-09-01); fix: sudo snap set ollama host=0.0.0.0:11434 (or change the apt startup args) then restart, after which containers can reach it at 172.17.0.1:11434. Note 0.0.0.0 exposes the service to the LAN β€” configure the firewall as needed.
  • Conflicts: MaxKB Γ— open-webui on the same machine β€” both are "knowledge base Q&A" tools with overlapping positioning, keep only one (possible-conflict, static judgment: different ports but overlapping positioning); ollama Γ— MaxKB compatible (MaxKB only reads the ollama API, no shared write surface); no shared write surfaces with other tools on this site.
  • China network: ollama binary via gh-proxy (measured); models via ModelScope GGUF import (measured) or the official registry (may time out); MaxKB image via the daocloud accelerator (measured).

FAQ

  1. Why MaxKB instead of open-webui's knowledge base? β†’ open-webui's RAG is an add-on feature; MaxKB is a dedicated knowledge base Q&A console (fuller document parsing, embeddable in business systems, Chinese UI); pick one of the two.
  2. Does data leave the machine? β†’ the model runs in local ollama and the knowledge base in a local container β€” nothing is uploaded to the cloud; only image pulls/upgrades use the network.
  3. Answers are poor? β†’ switch to a bigger model (start at 7B, 14B better); split documents finer (one topic per document); tune retrieval parameters in the app settings.
  4. Container cannot reach ollama (connection refused)? β†’ snap/apt ollama listens on 127.0.0.1 only; run sudo snap set ollama host=0.0.0.0:11434 and restart the ollama service (measured fix), then set the API URL in MaxKB to http://172.17.0.1:11434 (WSL/Linux bridge) or http://host.docker.internal:11434 (Docker Desktop).
  5. Can I embed it in my own website/system? β†’ Yes β€” MaxKB apps have an "embed" feature (HTML snippet), documented officially (not measured).
  6. Does it work on Mac/Windows? β†’ Yes: Docker Desktop runs MaxKB; ollama has official installers; inside WSL2 the path is the same as this guide.
  7. Answers do not cite the knowledge base / are wrong? β†’ three checks (measured 2026-09-01): β‘  similarity threshold too high (local text2vec Chinese: use <= 0.2); β‘‘ app prompt missing the {data} placeholder (paragraphs are not injected); β‘’ edited config but did not re-publish (chat reads the published snapshot). Compare against evidence Β§6.4.
  8. Any notes on driving MaxKB via the API? β†’ publish is a PUT; creating an app must include prologue; PUT updates must include knowledge_id_list; no_references_setting.status only accepts ai_questioning/designated_answer. Measured details in evidence Β§6.4.

Verification evidence

Every combo is measured in an isolated environment (smoke + write-surface check); unmeasured items are honestly marked in the text, and measurement dates are listed in the verification section below.

Verified 2026-09-01 Β· TTL expires 2027-02-28 (180 days)

  • MaxKB image pull + container start + login + containerβ†’ollama connectivity (2026-09-01, WSL Ubuntu, dockerd 29.1.3): local repro log 2026-09-01
  • daocloud pull of 1panel/maxkb:latest 4.62GB OK; container Up + 8080 mapping + PostgreSQL 17.10 ready + "MaxKB started."
  • default account admin / MaxKB@123.. login API returns a token (OK)
  • snap ollama listens on 127.0.0.1 only β†’ after host=0.0.0.0:11434, container reaches the ollama API at 172.17.0.1:11434 ({"version":"0.32.14"})
  • MaxKB "create knowledge base β†’ upload doc β†’ vectorize β†’ app β†’ Q&A" full API chain (2026-09-01 evening, same environment): same evidence file Β§6
  • created SIMPLE app + PUT publish (is_publish=true); open-book Q&A via POST /admin/api/chat_message/<chat_id>
  • asked "MAXKB_PROBE_TOKEN ηš„ε«δΉ‰ζ˜―δ»€δΉˆοΌŸ" β†’ answer "MAXKB_PROBE_TOKEN ηš„ε«δΉ‰ζ˜― trove-rag-test-passed-20260901。" β€” verbatim match with the knowledge base fact (retrieval β†’ vector β†’ prompt β†’ local model generation full chain OK)
  • complete pitfall list (8 items: similarity threshold/{data} placeholder/must re-publish after editing etc.) in evidence Β§6.4
  • Not measured (stated honestly): official Docker Hub direct pull not tested (daocloud covers the China path)
  • ollama side reuses existing measurements: local repro log 2026-08-29 (0.33.2 + qwen2.5-0.5b import + CPU smoke)

Related problems

← All combos ｜ Tool Catalog ｜ Hit a problem? Submit a helpdesk card