init

OLLAMA_DOCKER.md

@@ -0,0 +1,493 @@
+# Ollama Docker Compose 部署指南
+
+## 📋 概述
+
+现在 Mem0 Server 的 docker-compose.yaml 已经包含了 Ollama 服务，所有组件都可以通过 Docker Compose 统一管理。
+
+---
+
+## 🏗️ 新架构
+
+### 技术架构
+```
+┌─────────────┐
+│   Mem0 App  │ (FastAPI, port: 8888)
+└──────┬──────┘
+       │
+       ├──→ ┌─────────────┐
+       │    │   Ollama    │ (port: 11434)
+       │    │  LLM+AI     │
+       │    └─────────────┘
+       │
+       ├──→ ┌─────────────┐
+       │    │  ChromaDB   │ (Embedded)
+       │    └─────────────┘
+       │
+       └──→ ┌─────────────┐
+            │   SQLite    │ (Embedded)
+            └─────────────┘
+```
+
+### 服务列表
+- `mem0` - FastAPI 应用（端口 8888）
+- `ollama` - Ollama AI 服务（端口 11434）
+
+---
+
+## 🚀 快速开始
+
+### 方式 1：使用 GPU（推荐）
+
+如果您的机器有 NVIDIA GPU：
+
+```bash
+# 启动所有服务
+docker-compose --profile gpu up -d
+
+# 查看状态
+docker-compose ps
+
+# 查看日志
+docker-compose logs -f ollama
+```
+
+### 方式 2：仅使用 CPU
+
+如果没有 GPU：
+
+```bash
+# 启动所有服务（不使用 GPU profile）
+docker-compose up -d
+
+# 注意：Ollama 在 CPU 模式下可能较慢
+```
+
+---
+
+## 📊 docker-compose.yaml 配置说明
+
+### Ollama 服务配置
+
+```yaml
+ollama:
+  image: ollama/ollama:latest
+  container_name: ollama
+  restart: on-failure
+  networks:
+    - mem0_network
+  healthcheck:
+    test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
+    interval: 5s
+    timeout: 5s
+    retries: 10
+    start_period: 60s  # 给 Ollama 60 秒启动时间
+  volumes:
+    - ollama_data:/root/.ollama  # 持久化模型数据
+  ports:
+    - "11434:11434"  # 暴露 Ollama API
+  profiles: ["gpu"]  # GPU 配置
+  deploy:
+    resources:
+      reservations:
+        devices:
+          - driver: nvidia
+            count: all
+            capabilities: [gpu]
+```
+
+### Mem0 服务配置更新
+
+```yaml
+mem0:
+  environment:
+    - OLLAMA_HOST=http://ollama:11434  # 使用 Docker 网络访问 Ollama
+    - OLLAMA_LLM_MODEL=llama3.2
+    - OLLAMA_EMBEDDER_MODEL=nomic-embed-text
+  depends_on:
+    ollama:
+      condition: service_healthy  # 等待 Ollama 健康检查通过
+```
+
+---
+
+## 🔧 使用步骤
+
+### 1. 首次启动
+
+```bash
+# 启动服务
+docker-compose --profile gpu up -d
+
+# 等待 Ollama 启动完成（约 60 秒）
+docker-compose logs -f ollama
+
+# 查看已加载的模型
+docker exec ollama ollama list
+```
+
+### 2. 下载模型
+
+首次使用需要下载模型：
+
+```bash
+# 进入 Ollama 容器
+docker exec -it ollama bash
+
+# 下载 LLM 模型
+ollama pull llama3.2
+
+# 下载嵌入模型
+ollama pull nomic-embed-text
+
+# 退出
+exit
+```
+
+或者一次性下载：
+
+```bash
+docker exec ollama ollama pull llama3.2
+docker exec ollama ollama pull nomic-embed-text
+```
+
+### 3. 测试 Ollama
+
+```bash
+# 测试 Ollama API
+curl http://localhost:11434/api/tags
+
+# 测试生成
+curl http://localhost:11434/api/generate -d '{
+  "model": "llama3.2",
+  "prompt": "Hello, how are you?"
+}'
+```
+
+### 4. 测试 Mem0 API
+
+```bash
+# 访问 API 文档
+http://localhost:8888/docs
+
+# 创建记忆
+curl -X POST http://localhost:8888/memories \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "你好"},
+      {"role": "assistant", "content": "你好！有什么可以帮助你的？"}
+    ],
+    "user_id": "test_user"
+  }'
+```
+
+---
+
+## 💾 数据持久化
+
+### Ollama 数据卷
+- **名称**: `ollama_data`
+- **路径**: `/root/.ollama`
+- **内容**: 下载的模型文件、配置等
+
+### 查看数据卷
+```bash
+# 查看数据卷信息
+docker volume inspect ollama_data
+
+# 查看数据卷位置
+docker volume ls | grep ollama_data
+```
+
+---
+
+## ⚙️ 配置选项
+
+### 使用不同的模型
+
+编辑 `.env` 文件：
+
+```bash
+OLLAMA_LLM_MODEL=mistral
+OLLAMA_EMBEDDER_MODEL=mxbai-embed-large
+```
+
+重启服务：
+```bash
+docker-compose --profile gpu up -d
+```
+
+### 调整 Ollama 资源
+
+如果需要更多 GPU 资源：
+
+```yaml
+deploy:
+  resources:
+    reservations:
+      devices:
+        - driver: nvidia
+          device_ids: ['0', '1']  # 使用特定 GPU
+          capabilities: [gpu]
+```
+
+---
+
+## 🔍 故障排查
+
+### Ollama 启动失败
+
+```bash
+# 查看详细日志
+docker-compose logs ollama
+
+# 检查健康状态
+docker-compose ps ollama
+
+# 进入容器调试
+docker exec -it ollama bash
+```
+
+### 模型下载慢
+
+```bash
+# 设置国内镜像（如果可用）
+export OLLAMA_MODELS=https://mirror.ghproxy.com/https://github.com/ollama/ollama/releases/download
+
+# 或者手动下载模型文件后挂载
+```
+
+### GPU 不可用
+
+```bash
+# 检查 NVIDIA Docker 是否安装
+nvidia-smi
+
+# 检查容器是否识别 GPU
+docker exec ollama nvidia-smi
+
+# 如果没有 GPU，使用 CPU 模式
+docker-compose up -d
+```
+
+### Mem0 无法连接 Ollama
+
+```bash
+# 检查网络连通性
+docker exec mem0 ping ollama
+
+# 检查 Ollama 是否运行
+docker exec mem0 curl http://ollama:11434/api/tags
+
+# 查看依赖关系
+docker-compose ps
+```
+
+---
+
+## 🎯 优势特点
+
+### 统一管理
+- ✅ 所有服务通过 docker-compose 管理
+- ✅ 一键启动/停止
+- ✅ 自动处理依赖关系
+
+### 数据隔离
+- ✅ Ollama 数据独立存储
+- ✅ 不会污染宿主机环境
+- ✅ 易于备份和迁移
+
+### 网络自动化
+- ✅ Docker 网络自动配置
+- ✅ 服务间通过服务名通信
+- ✅ 无需手动配置 IP
+
+### 健康检查
+- ✅ 自动检测 Ollama 状态
+- ✅ Mem0 等待 Ollama 就绪
+- ✅ 提高系统可靠性
+
+---
+
+## 📈 性能优化
+
+### GPU 加速
+```yaml
+# 启用 GPU 支持
+profiles: ["gpu"]
+deploy:
+  resources:
+    reservations:
+      devices:
+        - driver: nvidia
+          count: all
+          capabilities: [gpu]
+```
+
+### 内存优化
+```yaml
+# 限制最大内存使用
+deploy:
+  resources:
+    limits:
+      memory: 8G
+    reservations:
+      memory: 4G
+```
+
+### 并发优化
+```bash
+# 设置 Ollama 并发数
+docker exec ollama sh -c 'echo "OLLAMA_NUM_PARALLEL=4" >> /root/.ollama/config.json'
+```
+
+---
+
+## 🔄 常用命令
+
+### 启动服务
+```bash
+# 带 GPU 支持
+docker-compose --profile gpu up -d
+
+# 仅 CPU
+docker-compose up -d
+```
+
+### 停止服务
+```bash
+docker-compose --profile gpu down
+```
+
+### 查看状态
+```bash
+# 查看所有服务
+docker-compose ps
+
+# 查看 Ollama 日志
+docker-compose logs -f ollama
+
+# 查看 Mem0 日志
+docker-compose logs -f mem0
+```
+
+### 重启服务
+```bash
+# 重启 Ollama
+docker-compose restart ollama
+
+# 重启 Mem0
+docker-compose restart mem0
+
+# 重启所有
+docker-compose restart
+```
+
+### 进入容器
+```bash
+# 进入 Ollama 容器
+docker exec -it ollama bash
+
+# 进入 Mem0 容器
+docker exec -it mem0 bash
+```
+
+### 管理模型
+```bash
+# 列出已安装的模型
+docker exec ollama ollama list
+
+# 下载新模型
+docker exec ollama ollama pull mistral
+
+# 删除模型
+docker exec ollama ollama rm llama3.2
+
+# 查看模型信息
+docker exec ollama ollama show llama3.2
+```
+
+---
+
+## 💡 最佳实践
+
+### 1. 首次部署
+```bash
+# 1. 启动服务
+docker-compose --profile gpu up -d
+
+# 2. 等待 Ollama 就绪
+sleep 60
+
+# 3. 下载所需模型
+docker exec ollama ollama pull llama3.2
+docker exec ollama ollama pull nomic-embed-text
+
+# 4. 测试 API
+curl http://localhost:8888/docs
+```
+
+### 2. 日常使用
+```bash
+# 启动
+docker-compose --profile gpu up -d
+
+# 停止
+docker-compose --profile gpu down
+
+# 重启
+docker-compose --profile gpu restart
+```
+
+### 3. 数据备份
+```bash
+# 备份 Ollama 数据
+docker run --rm \
+  -v ollama_data:/data \
+  -v $(pwd):/backup \
+  alpine tar czf /backup/ollama_backup.tar.gz /data
+```
+
+### 4. 恢复数据
+```bash
+# 恢复 Ollama 数据
+docker run --rm \
+  -v ollama_data:/data \
+  -v $(pwd):/backup \
+  alpine tar xzf /backup/ollama_backup.tar.gz -C /
+```
+
+---
+
+## 🆘 常见问题
+
+### Q1: Ollama 启动很慢？
+**A:** Ollama 首次启动需要加载模型，可能需要 60 秒。健康检查配置了 `start_period: 60s` 来等待。
+
+### Q2: 如何切换模型？
+**A:** 修改 `.env` 中的 `OLLAMA_LLM_MODEL`，然后重启服务，并确保新模型已下载。
+
+### Q3: GPU 内存不足？
+**A:** 使用更小的模型（如 `phi3`），或限制并发数。
+
+### Q4: 如何完全清理？
+**A:** 
+```bash
+docker-compose --profile gpu down -v  # 删除所有数据卷
+```
+
+### Q5: 可以在没有 GPU 的情况下运行吗？
+**A:** 可以，但速度较慢。使用 `docker-compose up -d`（不带 gpu profile）。
+
+---
+
+## 📚 相关文档
+
+- [README.md](./README.md) - 项目主文档
+- [TECH_STACK.md](./TECH_STACK.md) - 技术架构说明
+- [QUICK_START.md](./QUICK_START.md) - 快速入门
+- [DEPLOYMENT.md](./DEPLOYMENT.md) - 详细部署指南
+
+---
+
+现在所有服务都集成在 docker-compose.yaml 中，管理更加简单统一！🎉