ChromaDB+Ollama+Open WebUI ，本地 AI 知识库全流程操作手册(深度实践版)

Tinghui
14 阅读9分钟

本手册旨在指导用户在 macOS 上搭建一套完全私有化、零成本、高安全性的 AI 知识库系统。该系统整合了 ChromaDB（本地向量数据库）+ Ollama（本地大模型）+ Open WebUI（图形化交互）。

🔗 资源下载地址汇总

在开始之前，请根据您的系统环境下载并安装以下必要组件：

组件说明官方下载链接
Python基础运行环境 (推荐 3.10+)python.org/downloads
Ollama本地 AI 推理引擎ollama.com/download
Docker容器化部署 Open WebUIdocker.com/products/do…
HomebrewmacOS 软件包管理器 (可选)brew.sh

🌟 为什么选择本地 AI 知识库？

拥有了一个**“具备语义理解能力的私人图书馆”**。它与传统的文件夹搜索（靠关键词匹配）有着本质的区别。

1. 语义搜索：懂你的“意思”，而不是“字面量”

这是向量数据库最强大的地方。

  • 传统搜索：如果你搜“运动”，它只能找到包含“运动”这两个字的文件。
  • ChromaDB 搜索：如果你搜“锻炼身体的方法”，它能帮你找到包含“跑步”、“游泳”或“健身房指南”的文档，因为它理解这些词在语义上是相关的。

2. 打造私人 AI 知识助手 (RAG)

这是目前最火的应用方向。你可以将 ChromaDB 作为一个“外挂大脑”：

  • 操作方式：当你向 AI（如 GPT-4 或本地的 Ollama/Llama3）提问时，先让 ChromaDB 在你的本地文档里找到相关的知识段落，然后把这些段落喂给 AI。
  • 效果：AI 就能基于你自己的私有数据（比如你的会议记录、学习笔记、公司内部文档）来回答问题，且不会泄露隐私，也不会产生“幻觉”。

3. 智能去重与关联发现

  • 内容去重：当你存入一段新知识时，可以先让数据库查一下是否有极其相似的内容，避免知识碎片化。
  • 发现联系：你可以通过一段话找到另一段虽然措辞不同但逻辑相关的笔记，帮助你串联知识点，产生新的灵感。

4. 场景举例

场景具体用途
学习笔记搜“深度学习的数学基础”，自动关联出你过去一年存的所有相关数学公式和原理。
代码片段搜“如何实现用户登录”，它能从你存的成百上千个代码片段中找到最接近的逻辑实现。
法律/医学文档在海量的专业术语中，通过描述症状或案例背景，快速定位到相关的条文或病例。
个人日记搜“去年夏天最开心的事”，它能跨越日期帮你找回那些充满情绪色彩的瞬间。

5. 为什么选本地？

  • 隐私安全：你的数据永远留在你自己的硬盘上，不会上传到任何云端。
  • 零成本：不需要支付云端数据库的高昂费用。
  • 离线可用：没有网络也能进行深度的知识检索。

🛠️ 第一阶段：环境检查与数据库安装

  1. 检查 Python 环境，打开的**本地终端（Terminal 或 PowerShell）**中输入以下命令并按回车：
python --version
  • 如上面的命令没反应，是因为在 macOS 上，对应的安装工具通常叫 pip3。修改为以下命令
python3 --version

结果说明：

  • 如果显示 Python 3.x.x：说明你已经安装好了，我们可以继续下一步。
  • 如果显示“未找到命令”或“command not found” ：说明你的电脑还没有安装 Python，或者没有配置环境变量。
  1. 安装 ChromaDB 向量数据库
python3 -m pip install chromadb pysqlite3-binary

操作指引：

  • 复制上面的命令并在你的终端中运行。
  • 安装过程中可能会出现很多进度条，请耐心等待它完成。
  • 安装中，可能会遇到了一点兼容性问题，是因为 macOS 自带的 SQLite 版本通常已经足够新，可以尝试另一种安装方式。先安装核心数据库
python3 -m pip install chromadb
  • 验证安装
python3 -c "import chromadb; print('ChromaDB 准备就绪！')"
  • 如果运行后输出了“ChromaDB 已经准备就绪！”，那么恭喜你，最难的一步已经跨过去了！

注：没有出现红色的 ERROR，就说明安装已经成功了。 Warning（黄色文字）通常只是提醒你 pip 版本较旧，或者是某些文件安装路径的建议，并不会影响程序的正常运行。

  • 如果报错，（提示 SQLite 版本过低），我们再尝试安装替代补丁：
python3 -m pip install pysqlite3

太棒了！现在本地环境已经完全具备了运行向量数据库的能力。接下来的目标是：在你电脑上创建一个专门的文件夹，并把管理代码放进去。

📂 第二阶段：脚本创建本地知识库

  1. 终端创建工作文件夹，建议将所有知识库相关文件统一存放。
mkdir -p ~/Documents/MyKnowledgeBase
cd ~/Documents/MyKnowledgeBase
  1. 创建核心管理脚本 kb.py

该脚本负责将文本转化为“向量”并存入数据库。直接复制以下整段代码并粘贴到终端回车，即可生成脚本。

cat <<EOF > kb.py
import chromadb
import os
import sys

# 初始化数据库
client = chromadb.PersistentClient(path="./data")
collection = client.get_or_create_collection(name="my_docs")

def add_info(text):
    doc_id = str(hash(text))
    collection.add(documents=[text], ids=[doc_id])
    print(f"✅ 已存入: {text}")

def search_info(query):
    results = collection.query(query_texts=[query], n_results=2)
    print(f"\n🔍 搜索结果:")
    for doc in results['documents'][0]:
        print(f" - {doc}")

if __name__ == "__main__":
    if len(sys.argv) > 2:
        if sys.argv[1] == "add": add_info(sys.argv[2])
        elif sys.argv[1] == "query": search_info(sys.argv[2])
EOF

3.测试基础功能

存入一条知识

python3 kb.py add "Manus 是一个超级好用的 AI 助手。"

搜索相关内容

python3 kb.py query "Manus 是谁开发的？"

后续进阶：将现有文档（如 .txt, .md, .pdf, .docx）导入 ChromaDB 是构建知识库最实用的功能。为了实现这个功能，需要对之前的脚本进行升级，增加一个“读取文件”的模块等。后续可搜索升级增强本地kb.py脚本，已实现导入文件，处理PDF等。

🤖 第三阶段：本地 AI 引擎 (Ollama) 联动

如果你追求极致隐私，不希望任何数据联网，可以在本地运行 Ollama。你已经有了 Python 环境和 ChromaDB，继续按一下步骤

  1. 安装 Ollama：去 ollama.com 下载并安装。
  2. 下载模型：打开终端，输入：
ollama run llama3

下载完成后，可以直接在终端和它聊天，按 Ctrl+D 退出。

  1. 连接代码：安装 Python 连接库：
python3 -m pip install ollama
  1. 创建 RAG 对话脚本 ai_kb.py。该脚本实现了 RAG 流程，让 AI 根据你的本地知识回答问题。
cat <<EOF > ai_kb.py
import chromadb
import ollama

db_client = chromadb.PersistentClient(path="./data")
collection = db_client.get_collection(name="my_docs")

def ask_my_kb(question):
    results = collection.query(query_texts=[question], n_results=3)
    context = "\n".join(results['documents'][0])
    prompt = f"你是一个基于本地知识库的助手。请根据以下参考内容回答问题。\n\n参考内容：\n{context}\n\n问题：{question}"
    
    response = ollama.chat(model='qwen2.5:7b', messages=[
        {'role': 'user', 'content': prompt},
    ])
    print(f"\nAI 回答：\n{response['message']['content']}")

if __name__ == "__main__":
    import sys
    if len(sys.argv) > 1:
        ask_my_kb(sys.argv[1])
EOF

模型选择建议表

您的需求推荐模型命令
日常中文知识库（首选）Qwen 2.5 7Bollama run qwen2.5:7b
写代码、搞技术DeepSeek-Coderollama run deepseek-coder-v2
追求极致速度（低配电脑）Llama 3.2 3Bollama run llama3.2:3b
追求最强逻辑（高配 32G+ 内存）Qwen 2.5 14B/32Bollama run qwen2.5:14b

如何切换模型？

只需要在终端运行一次 ollama run 模型名，Ollama 就会自动下载。下载完成后，修改你 ai_kb.py 脚本里的这一行即可：

Python

response = ollama.chat(model='新模型名', messages=[...])

🖥️ 第四阶段：图形化界面 (Open WebUI) 部署

如果你安装了 Open WebUI，它自带了非常强大的 RAG（检索增强生成）功能，完全不需要写代码：

  • 操作步骤：

    1. 打开 Open WebUI 界面。
    2. 点击左侧的 “Workspace”（工作区） -> “Documents”（文档） 。
    3. 直接将你的文件（PDF, Word, TXT）拖进去。
    4. 链接方式：在聊天框输入 # 号，后面跟着你的文档名称，AI 就会自动检索该文档内容来回答你。

  • 底层原理：它其实在后台也运行着一个类似 ChromaDB 的向量数据库，只是它帮你把“上传、切片、存储”全部图形化了

完美的图形化体验

  1. 安装 Open WebUI（可以通过 Docker 一键安装）。
  2. 它会接管你的 Ollama 模型，并提供一个极其精美的界面。
  3. 你可以直接在它的界面上管理成千上万个文档，而不需要再通过命令行 python3 kb.py add 这么辛苦地操作。

安装Open WebUI

第一步：安装 Docker (如果还没安装)

  1. 访问 Docker 官网 下载并安装 Docker Desktop for Mac。
  2. 安装完成后启动 Docker Desktop，确保你在菜单栏能看到“小鲸鱼”图标，并且状态显示为 Running。

第二步：一键运行 Open WebUI

打开你的终端（Terminal），直接复制并粘贴以下命令。这条命令会自动下载并运行 Open WebUI，同时将其连接到你已经安装好的 Ollama 上：

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main

第三步：访问界面

  1. 等待命令运行完成（第一次下载镜像可能需要几分钟）。
  2. 打开浏览器，访问：http://localhost:3000
  3. 注册账号：第一次登录需要创建一个管理员账号 。由于是全本地运行，你可以随便设置账号密码，它只存在你自己的电脑上。

第四步：在界面中链接知识库

进入界面后，你就不再需要写代码来维护知识库了：

  1. 选择模型：在上方选择你之前下载的 qwen2.5:7b。
  2. 上传文档：点击左下角的 "Workspace" -> "Documents" ，直接把你的文件拖进去。
  3. 开始对话：回到聊天界面，输入 # 符号，选择你刚才上传的文档，AI 就会开始基于这些文档回答你的问题。

常见问题处理：

  • 如果访问不了 3000 端口：请确保 Docker 已经启动。
  • 如果找不到模型：在 Open WebUI 的设置里，确认连接地址是否为 http://host.docker.internal:11434 。Ollama 的默认端口 11434
  1. 配置连接地址

如果 Open WebUI 找不到模型，在设置的 Connections 中将 Ollama API 地址改为：host.docker.internal:11434

📈 第五阶段：日常维护与进阶

  • 模型更新：使用终端
ollama pull qwen2.5:7b
  • 数据备份：定期拷贝 ~/Documents/MyKnowledgeBase/data 文件夹到安全位置。
  • 升级pip工具：
python3 -m pip install --upgrade pip
  • 文档导入：在 Open WebUI 中使用 # 符号快速引用已上传的 PDF 或代码文件。
avatar
文章
阅读
粉丝