向量搜索修复完成总结

⚠️ **归档文档 — 数据已过时** 本报告为历史快照存档。当前版本 **v1.3.0-dev**，232 测试通过。 👉 最新工程状态请参阅 **[ENGINEERING_ALIGNMENT.md](ENGINEERING_ALIGNMENT.md)**

---

日期: 2026-03-31 状态: ✅ 代码修改完成，等待部署

---

🎯 修复内容

核心问题

# 修复前（backend/services/retrieval/vector.py:79-95）
# 使用 SHA256 哈希模拟向量，无语义意义
import hashlib
hash_obj = hashlib.sha256(text.encode('utf-8'))
hash_bytes = hash_obj.digest()
# ... 扩展到 1024 维

解决方案

# 修复后
# 调用真实的 BGE-M3 嵌入服务
async def embed_text(self, text: str) -> List[float]:
    response = await self._http_client.post(
        f"{self.embedding_api_url}/embed",
        json={"text": text, "normalize": True},
        timeout=30.0
    )
    return response.json()["embedding"]

---

📁 文件清单

新增文件（3 个）

文件	行数	说明
backend/services/embeddings/embedding_service.py	148	BGE-M3 嵌入 FastAPI 服务
backend/services/embeddings/Dockerfile	25	嵌入服务容器配置
backend/services/embeddings/requirements.txt	5	Python 依赖
scripts/rebuild_embeddings.py	104	重建文档向量脚本
deploy_vector_fix.sh	132	一键部署脚本
VECTOR_SEARCH_FIX_GUIDE.md	350+	详细部署指南

总计: 6 个新文件，~664 行代码

修改文件（5 个）

文件	修改	说明
docker-compose.yml	+42 行	添加 embedding 服务
backend/services/retrieval/vector.py	~80 行	替换 SHA256 为真实 API
.env.example	+4 行	添加 EMBEDDING_SERVICE_URL
.env.production	+4 行	添加 EMBEDDING_SERVICE_URL

总计: 5 个文件修改

---

🔧 技术架构

服务架构

┌─────────────────┐
│   API 服务      │
│  (FastAPI)      │
└────────┬────────┘
         │ HTTP
         ▼
┌─────────────────┐
│ BGE-M3 嵌入服务 │
│  (FastAPI)      │
│  端口: 8001     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ BGE-M3 模型     │
│ (sentence-trans)│
└─────────────────┘

数据流程

用户查询 → API → 嵌入服务 → BGE-M3 模型 → 向量
                                        ↓
                                    PostgreSQL
                                    (pgvector)
                                        ↓
                                    向量相似度搜索
                                        ↓
                                    相关文档

---

📊 资源需求

Docker 资源配置

embedding:
  deploy:
    resources:
      limits:
        cpus: '2.0'
        memory: 4G
      reservations:
        cpus: '0.5'
        memory: 2G

磁盘需求

项目	大小
BGE-M3 模型	~2.3 GB
Docker 镜像	~1.5 GB
向量数据	取决于文档数

网络需求

• 首次启动: 需要下载模型 (~2.3 GB)
• 后续运行: 无外部网络依赖

---

🚀 部署方式

方式 1: 一键部署（推荐）

cd /home/ai/zhineng-knowledge-system
bash deploy_vector_fix.sh

方式 2: 手动部署

参考 VECTOR_SEARCH_FIX_GUIDE.md 的详细步骤

---

✅ 验证方法

1. 嵌入服务健康检查

curl http://localhost:8001/health
# 预期: {"status":"healthy","model_loaded":true,"device":"cpu"}

2. 测试文本嵌入

curl -X POST http://localhost:8001/embed \
  -H "Content-Type: application/json" \
  -d '{"text":"气功的呼吸方法"}' | jq '.embedding | length'
# 预期: 1024

3. 测试向量搜索

curl -X POST http://localhost:8000/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"气功的呼吸方法","category":"气功","top_k":5}' | jq '.results[0]'
# 预期: 返回相关的气功文档，相似度 > 0.7

4. 检查向量数据库

docker exec zhineng-postgres psql -U zhineng -d zhineng_kb -c "
SELECT COUNT(*) as total,
       COUNT(embedding) as with_embedding
FROM documents;
"
# 预期: with_embedding = total（所有文档都有向量）

---

🎯 效果预期

语义搜索质量提升

指标	修复前	修复后
向量质量	🔴 随机	🟢 语义准确
搜索相关性	🔴 < 20%	🟢 > 80%
混合搜索	🔴 不工作	🟢 正常
GraphRAG	🔴 不工作	🟢 正常

性能指标

指标	值
单文本嵌入延迟	0.5-2 秒
批量嵌入（10）	2-5 秒
向量搜索延迟	< 100 ms
吞吐量	~30 文本/秒

---

📝 后续任务

立即执行

• [ ] 运行 deploy_vector_fix.sh 部署服务
• [ ] 等待模型加载完成（约 2-5 分钟）
• [ ] 运行 rebuild_embeddings.py 重建向量
• [ ] 测试向量搜索功能

可选优化

• [ ] 添加 GPU 加速（如果可用）
• [ ] 配置模型缓存持久化
• [ ] 添加嵌入服务监控
• [ ] 优化批量处理性能

---

🔍 故障排查

问题 1: 模型下载失败

# 检查网络连接
ping huggingface.co

# 手动预下载模型
docker run --rm -v $(pwd)/data/embedding_cache:/cache \
  python:3.11-slim bash -c "
  pip install sentence-transformers
  python -c 'from sentence_transformers import SentenceTransformer; SentenceTransformer(\"BAAI/bge-m3\", cache_folder=\"/cache\")'
"

问题 2: 内存不足

# 检查内存使用
free -h

# 减少其他容器内存限制
# 编辑 docker-compose.yml，降低 postgres 和 api 的内存限制

问题 3: 向量重建失败

# 查看详细错误
python3 scripts/rebuild_embeddings.py

# 检查嵌入服务日志
docker-compose logs -f embedding

# 手动测试单个文档
curl -X POST http://localhost:8001/embed \
  -H "Content-Type: application/json" \
  -d '{"text":"测试文本"}'

---

📚 相关文档

1. 详细部署指南: VECTOR_SEARCH_FIX_GUIDE.md
2. 安全加固报告: SECURITY_HARDENING_COMPLETION_REPORT.md
3. 代码审计报告: FULL_CODE_AUDIT_REPORT.md

---

🎉 总结

已完成

✅ 创建 BGE-M3 嵌入服务 ✅ 修复向量检索代码 ✅ 配置 Docker Compose ✅ 创建部署脚本和文档 ✅ 准备重建向量脚本

待执行

⏳ 部署嵌入服务 ⏳ 重建文档向量 ⏳ 验证搜索功能

---

下一步: 运行 bash deploy_vector_fix.sh 开始部署！