surinderlohat/searchkit

SearchKit

任何技术栈的插件式向量搜索 — 单个容器，零配置，可直接用于生产环境。

这是一个轻量级、可用于生产环境的FastAPI封装，基于嵌入式ChromaDB实现语义搜索和向量存储。通过单个Docker容器即可集成到任何技术栈中，无需单独部署ChromaDB服务器。

---

你可以用它构建什么？

该服务作为专用语义搜索层，可与主应用程序协同工作。以下是一些实际应用场景：

🔍 AI驱动搜索 — 用基于语义的搜索替代应用中的关键词搜索。用户搜索“舒适的跑鞋”时，即使商品描述写的是“轻便运动鞋”也能找到相关结果。

🤖 RAG（检索增强生成） — 在生成响应前向LLM提供相关上下文。在此存储文档，通过查询搜索，将顶部结果作为上下文传递给GPT/Claude等模型。

📄 文档相似性匹配 — 查找相关文章、工单或记录。例如“显示与此工单相似的支持工单”或“查找与此主题相关的博客文章”。

🛒 商品推荐 — 嵌入商品描述并找到语义相似的商品。无需协同过滤即可实现“查看此商品的用户还喜欢...”功能。

💬 FAQ与聊天机器人匹配 — 将用户问题与最接近的FAQ条目或支持文章匹配，即使表述完全不同也能准确对应。

🏷️ 智能标签与分类 — 通过与类别嵌入比较，自动对传入内容进行分类。

---

功能特性

• 🔍 通过REST API实现语义搜索
• 📦 嵌入式ChromaDB — 单个容器，无需额外服务
• 💾 通过Docker卷实现持久化存储 — 重启后数据不丢失
• 🔒 通过异步锁实现安全并发写入
• 🧠 使用BAAI/bge-small-en-v1.5自动生成嵌入向量
• 📚 多集合支持
• 📖 在/docs路径提供自动生成的API文档

---

快速开始

bash
docker run -d \
  --name searchkit \
  -p 9000:9000 \
  -v chroma-data:/app/chromadb \
  surinderlohat/searchkit:latest

或使用Docker Compose：

yaml
services:
  searchkit:
    image: surinderlohat/searchkit:latest
    container_name: searchkit
    restart: unless-stopped
    ports:
      - "9000:9000"
    environment:
      - CHROMA_PERSIST_DIR=/app/chromadb
      - EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
      - DEFAULT_COLLECTION=default
      - SENTENCE_TRANSFORMERS_HOME=/app/models
      - EMBEDDING_DEVICE=auto
      - LOG_LEVEL=INFO # INFO | DEBUG | WARNING | ERROR
      - LOG_FORMAT=text # text | json (生产环境建议用json)
      - MEMORY_WARN_MB=3500 # 内存超过此值时记录警告
      - MEMORY_LIMIT_MB=4000 # 超过此值时拒绝写入
    volumes:
      - ./data/chromadb:/app/chromadb # 向量数据库 — 直接存储在主机磁盘
      - ./data/models:/app/models # 模型缓存 — 直接存储在主机磁盘

---

API端点

完整交互式文档位于 http://localhost:9000/docs

插入/更新 — 单个文档

bash
curl -X POST http://localhost:9000/documents/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "default",
    "id": "doc_1",
    "text": "机器学习是人工智能的一个子集",
    "metadata": { "source": "wiki", "topic": "ai" }
  }'

插入/更新 — 批量文档

bash
curl -X POST http://localhost:9000/documents/upsert/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "default",
    "documents": [
      { "id": "doc_1", "text": "机器学习是人工智能的一个子集", "metadata": { "source": "wiki" } },
      { "id": "doc_2", "text": "FastAPI是现代Python Web框架", "metadata": { "source": "blog" } }
    ]
  }'

语义搜索

bash
curl -X POST http://localhost:9000/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "什么是人工智能？",
    "top_k": 5,
    "collection": "default",
    "where": { "source": "wiki" }
  }'

删除文档

bash
curl -X DELETE http://localhost:9000/documents/delete \
  -H "Content-Type: application/json" \
  -d '{ "collection": "default", "ids": ["doc_1"] }'

集合操作

GET    /collections           # 列出所有集合
GET    /collections/{name}    # 获取单个集合信息
DELETE /collections/{name}    # 删除集合

---

环境变量

---

容量指南

---

标签

---

致谢

该项目基于多个优秀的开源工具和模型构建。衷心感谢背后的团队和社区：

---

作者与许可

由 Surinder Singh 创建 — https://github.com/surinderlohat

基于 https://github.com/surinderlohat/searchkit/blob/main/LICENSE 许可。 © 2026 Surinder Singh。保留所有权利。