B BYOB Self-hosted vector DB for AI Agents

BYOB Project Documentation

给 AI Agent 使用的自部署向量数据库管理系统

BYOB 将文档导入、结构化解析、资源存储、混合检索、多模态召回、MCP 工具和 QA Agent 测试台整合到一套本地优先的知识库系统中。

开始部署 查看源码
Console
FastAPI
Worker
MCP
PostgreSQL
Redis
Qdrant
MinIO
Embedding
Rerank

Overview

项目介绍

BYOB 的定位不是 SaaS 平台，而是一套适合可信网络内部署的向量知识库系统。它帮助个人 或团队建立可由 AI Agent 调用的检索基础设施，并提供本地控制台来管理知识库、文档、 资源、chunk、治理状态、检索测试和 MCP 使用说明。

项目内置的 QA Agent 用于快速验证 MCP-backed RAG 效果。它可以接入 OpenAI-compatible Chat Completions，也可以在未配置 LLM 时返回抽取式 Markdown 答案，方便检查召回质量。

自部署优先

依赖服务通过 Docker Compose 启动，API、Worker、MCP 和前端可用一键脚本或按需独立运行。

面向 Agent

提供直接检索 API、MCP 工具和 asset 获取能力，让 Agent 可以以工具形式访问知识库。

可观察可测试

提供检索控制台、QA Agent、健康检查、metrics，以及 MinIO/Qdrant Web UI 入口。

Capabilities

核心能力

知识库与文档管理

创建知识库，上传文件、批量导入、文本导入、URL 导入和 JPEG/PNG 图片导入，按文件名和 SHA-256 hash 自动跳过重复文件。

解析与资源处理

支持 Markdown、TXT、HTML、PDF、DOCX、PPT、PPTX、XLSX、JPEG 和 PNG；MinerU content_list 优先，图片与解析资源保存到 MinIO。

向量检索

使用 Qdrant 存储 dense、sparse 和可选 visual vectors，支持高级检索、多查询检索、metadata、父级上下文和反馈记录。

知识库治理

导入时标注来源类型、权威等级和审核状态；正式检索默认只使用 published 文档。

Embedding 与 Rerank

默认通过 Infinity 运行 BGE embedding 和 reranker 服务，便于本地部署。

多模态 RAG

使用 CLIP 为图片资源建立视觉索引，文本查询可召回相关图片并与文本检索结果融合。

MCP Server

提供 stdio 和 Streamable HTTP transport，便于 MCP 客户端与 Agent 调用。

富文本渲染

控制台答案和 chunk 支持 Markdown、表格、公式、图片和安全 HTML 片段。

Deployment

快速开始与本地部署

1

准备环境

安装 Docker、Python 3.12+、uv、Node.js 20+ 和 Git。

python --version
uv --version
node --version
docker compose version
2

复制环境变量

从示例文件创建本地配置，生产环境必须替换默认密钥和服务凭据。

Copy-Item .env.example .env
3

启动基础设施

启动 PostgreSQL、Redis、Qdrant、MinIO、embedding 和 rerank 服务。

docker compose up -d
docker compose ps
4

安装依赖并迁移数据库

安装 Python 依赖并执行 Alembic 迁移。

uv sync --extra dev
uv run alembic upgrade head
5

创建管理员

创建第一个本地管理账号。

$env:BYOB_ADMIN_EMAIL = "admin@example.com"
$env:BYOB_ADMIN_PASSWORD = "replace-with-a-strong-password"
uv run python -m api.scripts.seed_admin
6

一键启动应用服务

跨 Windows、macOS、Linux 同时启动 API、Celery Worker、MCP Streamable HTTP 和前端控制台。

uv run python start-dev.py --install-frontend
7

按需拆分启动

开发时可以只启动部分服务，或者继续使用手动命令独立运行 API、Worker、MCP 和前端。

uv run python start-dev.py --services api frontend
uv run python start-dev.py --worker-only
uv run python start-dev.py --mcp-only

Configuration

关键环境变量

变量 用途 默认值
DATABASE_URL PostgreSQL 连接地址 postgresql+asyncpg://byob:byob@localhost:5432/byob
QDRANT_URL Qdrant HTTP 地址 http://localhost:6333
MINIO_ENDPOINT_URL MinIO API 地址 http://localhost:9000
EMBEDDING_ENDPOINT_URL Embedding 服务地址 http://localhost:7997
RERANK_ENDPOINT_URL Rerank 服务地址 http://localhost:7998
MCP_SERVER_URL QA Agent 使用的 MCP HTTP 地址 http://127.0.0.1:8010/mcp
AGENT_LLM_ENDPOINT_URL 可选 OpenAI-compatible Chat Completions 地址 未启用
AGENT_MAX_IMAGE_ASSETS QA Agent 每次最多传给多模态模型的图片数量 3
MULTIMODAL_RAG_ENABLED 是否启用图片视觉向量索引和 CLIP 检索 true
CLIP_PRELOAD_ON_STARTUP API、Worker 和 MCP 启动时是否预加载 CLIP true

MCP and RAG Test

MCP 与 QA Agent

BYOB MCP Server 暴露知识库列表、文档列表、普通检索、高级检索、多检索、 chunk 获取、asset 列表和 document asset 获取工具。召回结果会带出 chunk 中引用的图片/ 文件 manifest，控制台 QA Agent 可以把图片作为多模态输入交给 LLM。 大多数 MCP 客户端使用 stdio transport，控制台 QA Agent 使用 Streamable HTTP transport。 

uv run python -m api.app.mcp_server

uv run python -m api.app.mcp_server --transport streamable-http --host 127.0.0.1 --port 8010

QA Agent 流程

  1. 在控制台创建知识库并导入文档。
  2. 等待 Worker 完成解析、chunk 和 embedding。
  3. 打开 /agent 页面输入问题。
  4. Agent 通过 MCP 调用高级检索工具。
  5. 如果命中图片 asset，Agent 通过 MCP 拉取图片给多模态模型查看。
  6. 有 LLM 时生成答案，无 LLM 时返回抽取式 Markdown，并保留图片/文件链接。

API Surface

主要接口与工具

管理

  • POST /api/v1/auth/login
  • GET /api/v1/users
  • POST /api/v1/users

知识库与文档

  • GET /api/v1/knowledge-bases
  • POST /api/v1/knowledge-bases/{kb_id}/documents/batch
  • PATCH /api/v1/documents/{document_id}/governance
  • GET /api/v1/documents/{document_id}/assets
  • GET /api/v1/documents/{document_id}/chunks

检索

  • POST /api/v1/retrieval/search
  • POST /api/v1/retrieval/search/advanced
  • POST /api/v1/retrieval/multi-search
  • POST /api/v1/retrieval/embed
  • POST /api/v1/agent/ask

MCP

  • list_knowledge_bases
  • advanced_search_knowledge_base
  • get_document_chunks
  • get_document_asset

Production Notes

生产部署建议

当前 Compose 文件主要用于依赖服务。长期自部署时，建议将 API、Worker、MCP Server 和前端纳入 systemd、Supervisor、PM2 或容器平台，并使用反向代理提供 HTTPS、访问日志和鉴权策略。检索 API 和 MCP 默认服务于可信网络内的 Agent， 不应直接暴露到公网。

  • 替换 JWT_SECRET_KEY、PostgreSQL 密码和 MinIO 凭据。
  • 为 PostgreSQL、Qdrant、MinIO、Redis 配置持久化和备份。
  • 只在可信网络暴露数据库、Redis、Qdrant、MinIO 和 MCP HTTP。
  • 公网入口建议只暴露前端和 API，并放在反向代理、VPN 或现有身份体系之后。
  • 正确设置 CORS_ALLOWED_ORIGINS 和前端公开 URL。
  • 监控 /healthz、/metrics、Worker 日志和存储容量。

English Summary

BYOB in English

BYOB is a self-hosted vector database management system for AI Agent retrieval. It provides document ingestion, asset storage, chunking, embeddings, Qdrant-backed search, reranking, MCP tools, and a local console QA Agent for RAG testing. The project is designed for trusted self-hosted environments rather than public SaaS operation.