OpenCode + Obsidian 本地 AI 知识库

基于 macOS + Ollama + Chroma + FastAPI 的本地 AI 知识库系统，支持语义搜索和自动索引。

系统架构

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Obsidian   │────▶│  知识库目录   │────▶│  API 服务   │
│   笔记前端   │     │   .md 文件   │     │  (含监控)   │
└─────────────┘     └──────────────┘     └──────┬──────┘
                                                │
┌───────────────────────────────────────────────┼────────────┐
│                                               ▼            │
│  ┌──────────┐    ┌──────────┐    ┌─────────────────────┐  │
│  │  Ollama  │◀───│  Chroma  │◀───│   向量索引存储       │  │
│  │ LLM+向量  │    │  :8000   │    │                     │  │
│  └──────────┘    └──────────┘    └─────────────────────┘  │
└────────────────────────────────────────────────────────────┘

核心功能

• 语义搜索：基于向量相似度的智能搜索
• LLM 增强：使用本地大模型生成回答
• 自动索引：文件变更自动更新向量库
• 图像支持：多模态模型处理图片
• 完全本地：数据不上云，隐私安全

环境要求

• macOS 14+ (Apple Silicon/Intel)
• Python 3.11+
• Docker Desktop
• Ollama
• 16GB+ 内存
• 20GB+ 磁盘空间

快速开始

1. 克隆仓库

git clone https://github.com/wangyinlong-wang/opencode-Obsidian-AI-.git
cd opencode-Obsidian-AI-

2. 一键部署

./deploy-full.sh

部署脚本会自动完成：

• 检查环境依赖
• 启动 Ollama 服务
• 下载所需模型（qwen3.5:9b, gemma4:e4b, shaw/dmeta-embedding-zh）
• 安装 Python 依赖
• 启动 Chroma 向量数据库
• 构建知识库索引
• 启动 API 服务

3. 日常使用

方式一：桌面快捷启动

双击桌面图标 "Obsidian AI KB.command"

方式二：命令行启动

./start.sh

方式三：手动启动各服务

# 1. 启动 Ollama
open -a Ollama

# 2. 启动 Chroma
docker-compose -p obsidian-kb up -d

# 3. 启动 API（含文件监控）
python3 kb_api_full.py

使用方法

API 搜索

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query":"你的问题","use_llm":true}'

命令行搜索

# 使用快捷脚本
~/.claude/skills/obsidian-kb.sh search "关键词"

# 或直接调用
python3 chroma_kb_v2.py --search "关键词"

手动索引

# 重新索引所有文件
python3 chroma_kb_v2.py --index

# 或调用 API
curl -X POST http://localhost:8080/index

项目结构

.
├── kb_api_full.py          # 主 API 服务（集成文件监控）
├── chroma_kb_v2.py         # Chroma 向量库封装
├── kb_indexer_v2.py        # 本地 JSON 索引（备用）
├── deploy-full.sh          # 一键部署脚本
├── start.sh                # 一键启动脚本
├── docker-compose.yml      # Chroma 容器配置
├── requirements.txt        # Python 依赖
└── README.md              # 本文件

核心组件

模型配置

模型	用途	大小
qwen3.5:9b	文本问答（备用）	9.7 GB
gemma4:e4b	多模态问答（主用）	11 GB
shaw/dmeta-embedding-zh	中文向量嵌入	545 MB

服务端口

服务	端口	说明
API	8080	REST API + 文件监控
Chroma	8000	向量数据库
Ollama	11434	LLM 服务

自动索引机制

系统通过 watchdog 监控文件变更：

1. 监控范围：.md, .txt, .mdx 文件
2. 防抖时间：3 秒（避免频繁索引）
3. 自动处理：创建、修改、删除自动同步到向量库
4. 无需手动：在 Obsidian 中正常编辑即可

API 接口

健康检查

GET http://localhost:8080/health

语义搜索

POST http://localhost:8080/search
Content-Type: application/json

{
  "query": "搜索关键词",
  "top_k": 5,
  "threshold": 0.5,
  "use_llm": true
}

获取统计

GET http://localhost:8080/stats

重置索引

POST http://localhost:8080/reset

故障排查

Ollama 连接失败

# 检查服务状态
ollama ps
curl http://localhost:11434/api/version

# 重启服务
killall ollama
open -a Ollama

Chroma 启动失败

# 检查容器状态
docker ps | grep obsidian

# 手动启动
docker-compose -p obsidian-kb up -d

API 服务无法启动

# 检查端口占用
lsof -i :8080

# 查看日志
tail -f kb_api_full.log

性能指标

指标	数值	备注
索引速度	~1秒/文件	取决于文件大小
搜索延迟	<500ms	含向量计算
LLM 响应	5-15秒	取决于问题复杂度
向量维度	768	dmeta-embedding-zh
内存占用	~12GB	含 Ollama + API

安全说明

• 所有数据本地存储，不上传云端
• API 默认绑定本地地址，不外网暴露
• 支持通过环境变量配置访问控制

更新日志

v2.1.0 (2026-04-28)

• 集成文件监控到 API 服务
• 简化启动流程（3个服务→3个服务，但监控内置）
• 支持 gemma4 多模态模型

v2.0.0 (2026-04-28)

• 切换到 Chroma 向量数据库
• 新增 Docker 部署支持

v1.0.0 (2026-04-28)

• 初始版本
• 基于本地 JSON 索引

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

如有问题，请检查服务日志或提交 GitHub Issue。