AI导哈

文档搜索引擎

doc-hub是一个多语料库文档搜索引擎，支持混合向量和全文检索，通过MCP协议为LLM代理提供服务。

  • by kingfly55
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 kingfly55/doc-hub

使用说明

doc中心

具有混合矢量+全文检索的多语料库文档搜索引擎，通过MCP（模型上下文协议）公开，供LLM代理使用。

它做什么

doc-hub从各种来源获取文档，将其解析为语义上有意义的块，用可插拔的嵌入器嵌入它们，用VectorChord在PostgreSQL中对它们进行索引，并通过MCP服务器或CLI提供混合搜索（矢量KNN+BM25全文，通过RRF融合）。

插件系统允许您添加新的获取器、解析器和嵌入器，而无需修改dochub本身。

安装

doc-hub是从GitHub安装的（未发布到PyPI）。

# Install globally from GitHub (recommended)
uv tool install --force git+https://github.com/kingfly55/doc-hub.git

# Or install globally from a local clone while developing
uv tool install --force /path/to/doc-hub

# Or run from a local clone without a global install
git clone https://github.com/kingfly55/doc-hub.git && cd doc-hub
uv sync
source .venv/bin/activate

验证：

doc-hub --help
man doc-hub
# fallback if your shell has not picked up the installed manpath yet
doc-hub man

man doc-hub 是已安装CLI的简明本地参考。 doc-hub man 是直接打印捆绑的手册页文本的内置回退。

支持的命令界面是统一的 doc-hub CLI。统一前的旧包装，如 doc-hub-search, doc-hub-pipeline, doc-hub-eval, doc-hub-sync-all，以及 doc-hub-mcp 不应该留在你的路径上。

需求

  • Python>=3.11
  • PostgreSQL与 VectorChord 扩展
  • Gemini API密钥（免费层工作）-或自定义嵌入式插件

快速启动

1.使用VectorChord启动PostgreSQL

docker run -d --name vchord-postgres \
  -e POSTGRES_PASSWORD=mypassword \
  -p 5432:5432 \
  tensorchord/vchord-postgres:latest

2.设置环境变量

对于全球 doc-hub 安装时，最持久的设置是doc-hub的XDG数据目录下的一个机器范围的env文件：

mkdir -p ~/.local/share/doc-hub
cat > ~/.local/share/doc-hub/env <<'EOF'
PGHOST=localhost
PGPORT=5433
PGUSER=postgres
PGPASSWORD=mypassword
PGDATABASE=postgres
GEMINI_API_KEY=your-key-here
EOF

您仍然可以直接在shell中导出值：

export GEMINI_API_KEY="your-key-here"
export PGHOST=localhost PGPORT=5433 PGUSER=postgres PGPASSWORD=mypassword PGDATABASE=postgres

或者创建一个 .env 工作目录中的文件--dochub使用 python-dotenv 并在回退到全局env文件之前自动加载它。

您还可以设置单个连接字符串：

export DOC_HUB_DATABASE_URL="postgresql://postgres:mypassword@localhost:5433/postgres"

3.为你的第一个语料库建立索引

doc-hub pipeline run --corpus pydantic-ai

4.搜索

doc-hub docs search --corpus pydantic-ai "how do I handle retries?"

# Search multiple corpora

doc-hub docs search --corpus pydantic-ai --corpus fastapi "retry middleware"

CLI参考

命令 描述
doc-hub man 打印内置手册页
doc-hub docs list 列出已注册的语料库
doc-hub docs browse 浏览语料库的持久化文档层次结构，包括短文档ID
doc-hub docs read 通过短文档ID读取文档（来自浏览输出）
doc-hub docs search 跨一个或多个必需的混合搜索CLI --corpus 价值观
doc-hub pipeline add 注册并索引一个新的语料库。使用 --interactive/-i 用于引导设置或通行证 --strategy 和 --url 直接。
doc-hub pipeline remove 删除语料库及其所有数据（需要用户密码）
doc-hub pipeline run 运行取回→ 解析→ 嵌入→ 索引→ 语料库的树形管道
doc-hub pipeline clean 通过LLM从获取的markdown中剥离导航、页脚和抓取工件
doc-hub pipeline logs 查看语料库的管道运行输出
doc-hub pipeline sync-all 为所有启用的语料库运行管道
doc-hub pipeline eval 评估检索质量
doc-hub serve mcp 启动MCP服务器

看 docs/user/cli-reference.md 查看完整的标志和示例。

MCP服务器

通过FastMCP显示六个工具。支持stdio（默认）、SSE和可流式传输的http。

# stdio (default — for Claude Desktop, Claude Code)
doc-hub serve mcp

# SSE (persistent service)
doc-hub serve mcp --transport sse --port 8340

# streamable-http
doc-hub serve mcp --transport streamable-http --port 8340

克劳德桌面/Claude代码配置

标准 （每个会话生成）：

{
  "mcpServers": {
    "doc-hub": {
      "command": "doc-hub",
      "args": ["serve", "mcp"],
      "env": { "GEMINI_API_KEY": "<key>" }
    }
  }
}

上海证券交易所 （连接到正在运行的服务）：

{
  "mcpServers": {
    "doc-hub": {
      "type": "sse",
      "url": "http://localhost:8340/sse"
    }
  }
}

看 docs/user/mcp-server.md 有关传输详细信息和systemd服务设置。

作为systemd服务运行

cat > ~/.config/systemd/user/doc-hub-serve-mcp.service << 'EOF'
[Unit]
Description=doc-hub MCP Server (SSE on :8340)
After=network.target postgresql.service

[Service]
Type=simple
WorkingDirectory=%h
ExecStart=%h/.local/bin/doc-hub serve mcp --transport sse --port 8340
Restart=always
RestartSec=10
Environment=HOME=%h
EnvironmentFile=%h/.local/share/doc-hub/env

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now doc-hub-serve-mcp.service

插件系统

doc-hub使用基于Python入口点的插件架构。三种插件类型：

插件类型 入口点组 协议
费彻 doc_hub.fetchers doc_hub.protocols.Fetcher
解析器 doc_hub.parsers doc_hub.protocols.Parser
嵌入器 doc_hub.embedders doc_hub.protocols.Embedder

内置取料机： llms_txt, sitemap, git_repo, local_dir, direct_url. 内置解析器： markdown. 内置嵌入器： gemini.

看 docs/dev/plugin-authorization.md 获取编写插件的完整指南。

作为一个图书馆

import asyncio
from doc_hub.search import search_docs
from doc_hub.db import create_pool

async def main():
    pool = await create_pool()
    results = await search_docs("how do I define a tool?", pool=pool, corpora=["pydantic-ai"])
    for r in results:
        print(f"{r.heading} (sim={r.similarity:.3f})")
    await pool.close()

asyncio.run(main())

数据存储

doc-hub将本地数据（原始下载、块缓存、嵌入缓存）存储在XDG兼容目录中：

  1. DOC_HUB_DATA_DIR env-var（显式重写）
  2. $XDG_DATA_HOME/doc-hub 如果 XDG_DATA_HOME 已设置
  3. ~/.local/share/doc-hub （默认）
~/.local/share/doc-hub/
├── {corpus-slug}/
│   ├── raw/                       # downloaded .md files + manifest.json
│   └── chunks/
│       ├── chunks.jsonl           # parsed chunks
│       ├── embedded_chunks.jsonl  # chunks with embedding vectors
│       └── embeddings_cache.jsonl # embedding cache (keyed by content hash)
└── plugins/                       # local plugin files (alternative to entry points)
    ├── fetchers/
    ├── parsers/
    └── embedders/

环境变量

变量 默认值 描述
GEMINI_API_KEY -- 内置Gemini嵌入器需要
JINA_API_KEY -- 必需 sitemap fetcher和 llms_txt 和 --use-jina/--try-md
DOC_HUB_DATABASE_URL -- 完整连接字符串（覆盖PG*vars）
PGHOST localhost PostgreSQL主机
PGPORT 5432 PostgreSQL端口
PGDATABASE postgres 数据库名称
PGUSER postgres 数据库用户
PGPASSWORD -- 数据库密码（必填）
DOC_HUB_DATA_DIR ~/.local/share/doc-hub 覆盖数据目录
DOC_HUB_EVAL_DIR {data_root}/eval/ 覆盖eval目录
LOGLEVEL -- 设置为 DEBUG 用于详细输出

测试

# Unit tests (no DB or API key needed)
pytest tests/

# Integration tests (requires live DB + GEMINI_API_KEY)
pytest tests/ -m integration

文档

相关 MCP