Hybrid Memory Search

本地混合检索记忆服务：按 user_id 隔离存储，写入时同步 embedding，检索时在同一用户桶内做 BM25 + Dense 融合排序。

对接评测平台协议：POST /v1/add、POST /v1/search。更细的字段说明见 DEPLOY.md。

功能特点

• 隔离：user_id → 本地 bucket；用户之间互不可见
• 同步写入：Add 在文本落盘 + embedding 完成后再返回 200
• 混合检索：关键词（BM25）与语义向量互补
• 无外部库：记忆落在 ./store（JSON + npz），不需要 PostgreSQL / Redis
• Embedding 兼容：适配 SiliconFlow BAAI/bge-m3（不传 dimensions；超长文本向量侧截断）

快速部署

1. 环境要求

• Docker Engine + Compose（v1 docker-compose 或 v2 docker compose）
• 主机可访问 Embedding API（默认 SiliconFlow）

2. 配置

git clone <本仓库> hybrid_search
cd hybrid_search
cp .env.example .env
# 编辑 .env，至少填写 OPENAI_EMBEDDING_API_KEY

必填变量：

变量	说明
OPENAI_EMBEDDING_API_KEY	Embedding API Key
OPENAI_EMBEDDING_API_BASE	默认 https://api.siliconflow.cn/v1
OPENAI_EMBEDDING_MODEL	默认 BAAI/bge-m3
OPENAI_EMBEDDING_DIMENSIONS	默认 1024（bge-m3 实际不向 API 传该参数）

常用可选：PORT（默认 8000）、HYBRID_ALPHA（默认 0.5）。

3. 启动

mkdir -p store data
docker compose build
docker compose up -d
# 若只有旧版 CLI：
# docker-compose build && docker-compose up -d

curl http://127.0.0.1:8000/health
# {"status":"ok"}

也可用预构建镜像：

docker load -i hybrid-memory-1.0.0.tar
docker compose up -d

4. 云主机（如阿里云 ECS）额外步骤

1. 安全组放行 TCP 8000（或前面挂 Nginx 则放行 80/443）
2. 中国区若拉不动 Docker Hub，给 daemon 配镜像加速后再 docker pull python:3.11-slim
3. 内存紧张时可为容器设上限，例如：

docker update --memory=1024m --memory-swap=1536m hybrid-memory

4. 对外地址示例：http://<公网IP>:8000/v1/add、http://<公网IP>:8000/v1/search

5. 运维

docker compose logs -f --tail=200
docker compose restart
docker compose down          

接口速查

接口	方法	说明
/health	GET	健康检查（不会自动探活）
/v1/add	POST	评测平台写入；同步 embed
/v1/search	POST	评测平台检索；top_k 必填
/v1/buckets	GET	列出本地记忆桶

Add 示例：

curl -X POST http://127.0.0.1:8000/v1/add \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "demo:chunk-0",
    "user_id": "demo:user-1",
    "session_id": "demo:s0",
    "messages": [
      {"role": "user", "content": "I like green tea."},
      {"role": "assistant", "content": "Noted."}
    ]
  }'

Search 示例：

curl -X POST http://127.0.0.1:8000/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "green tea",
    "user_id": "demo:user-1",
    "top_k": 100
  }'