Skip to main content
Glama
Can-Y

xilinx-rag

by Can-Y
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

xilinx-rag

AI 驱动的 Xilinx/AMD FPGA 文档检索 MCP 服务器。混合检索 SQLite FTS5 关键词 + ChromaDB 向量嵌入 + RRF 融合，为 AI 编程助手（如 Kimi Code）提供 FPGA 数据手册、用户指南、应用笔记和 IP 文档的按需搜索。

功能

  • 双路混合检索 — FTS5 全文索引（精确关键词匹配）+ BGE 向量嵌入（中文语义匹配），RRF 融合排序

  • 7 个 MCP 工具 — search_docs、reindex_docs、get_doc_stats、list_doc_families、fetch_and_index、fetch_pdf、import_url_list

  • 系列/类型过滤 — 按 family（7_Series、Versal_Device…）和 doc_type（PG、UG、DS、XAPP…）精确筛选

  • 网页抓取 — fetch_and_index 抓取 URL 解析入索引，fetch_pdf 用 Headless Chromium 渲染 JS 页面并导出 PDF

  • 自动分类 — 下载的文档根据标题/URL 关键词自动归入 25+ FPGA 系列目录

  • 优雅降级 — 嵌入模型不可用时自动回退纯 FTS5 模式；markitdown 不可用时回退 pypdf2

  • 增量索引 — 文件哈希追踪，reindex_docs 只处理变更文件

Related MCP server: Dedalus MCP Documentation Server

快速开始

安装

git clone <repo-url>
cd doc_search_mcp
pip install -e .

下载嵌入模型（可选）

向量搜索需要模型 BAAI/bge-small-zh-v1.5（约 100 MB）。国内用户建议用镜像：

# 方式一：环境变量自动镜像（推荐）
set HF_ENDPOINT=https://hf-mirror.com        # Windows CMD
$env:HF_ENDPOINT = "https://hf-mirror.com"   # PowerShell

# 方式二：huggingface-cli
huggingface-cli download BAAI/bge-small-zh-v1.5

# 方式三：git clone 模型仓库
git clone https://hf-mirror.com/BAAI/bge-small-zh-v1.5
# 放入 ~/.cache/huggingface/hub/models--BAAI--bge-small-zh-v1.5/snapshots/

若无法联网下载模型，系统自动降级为纯 FTS5 关键词搜索模式，搜索功能不受影响。

准备文档库

将 Xilinx 文档（PDF）按系列放到子目录：

XilinxDocs/
├── 7_Series/           # Artix-7, Kintex-7, Virtex-7
├── UltraScale/         # Kintex/Virtex UltraScale
├── Versal_Device/      # Versal ACAP
├── Zynq_7000/
├── Zynq_UltraScale+_MPSoC/
├── Vivado/
├── Vitis_Products/
├── IP/                 # LogiCORE IP Product Guides
├── ISE/
└── ...

目录名即为文档系列（family），文件名中的 pg195、ug901 等自动提取为 doc_type/doc_id。

构建索引

# 指定文档库并构建（首次约 50 分钟，处理 3000+ PDF）
xilinx-rag index --docs-root H:\Users\admin\Documents\XilinxDocs

# docs-root 会自动保存到 ~/.xilinx-rag/config.json，后续只需：
xilinx-rag index

首次运行会：

  1. 解析所有 PDF（pypdf2），滑动窗口分块（500 字符/250 重叠）

  2. 写入 SQLite corpus.db（~1.1 GB），建 FTS5 全文索引（~29 秒）

  3. 生成向量嵌入写入 ChromaDB（~10 GB，含模型时约 5 小时）

查看状态

xilinx-rag stats
# 输出: {"total_chunks": 1648364, "index_status": "ready", "chroma_size_mb": 10377.7}

启动 MCP 服务器

xilinx-rag serve

在 MCP 客户端（如 Kimi Code config.toml）中配置为子进程启动即可。

MCP 工具

search_docs — 混合检索

search_docs(query="PCIe XDMA", top_k=5, family="IP", doc_type="PG")

返回 FTS5 + 向量 + RRF 融合排序结果，包含文本片段、源文件、页码、系列、文档类型、BM25/向量/融合分数。

reindex_docs — 重建索引

reindex_docs(force=True)   # force=True 全量重建，默认增量更新

get_doc_stats — 索引统计

get_doc_stats()
# → total_chunks, index_status, chroma_size_mb

list_doc_families — 列出系列

list_doc_families()
# → 所有 family 目录及文件数

fetch_and_index — 抓取网页

fetch_and_index(url="https://docs.xilinx.com/...", family="Vivado", save_html=True)

fetch_pdf — 导出 PDF

fetch_pdf(url="https://docs.xilinx.com/...", family="Versal_Device")

用 Playwright + Edge 渲染 JS 页面，自动探测 AMD 文档门户的 Fluid Topics PDF 附件。

import_url_list — 批量导入

import_url_list(file_path="urls.txt", family="IP")

配置

核心参数在 src/xilinx_rag/config.py：

参数

默认值

说明

DATA_DIR

~/.xilinx-rag/

索引/缓存目录

CHROMA_PATH

~/.xilinx-rag/chroma_db

ChromaDB 持久化存储

CHUNK_SIZE

500

分块大小（字符）

CHUNK_OVERLAP

250

分块重叠量

EMBED_MODEL

BAAI/bge-small-zh-v1.5

向量嵌入模型（512 维）

TOP_K_BM25

20

FTS5 候选数

TOP_K_VECTOR

20

向量候选数

RRF_K

60

RRF 融合平滑常数

文档根目录优先级：CLI --docs-root > 环境变量 XILINX_DOCS_ROOT > ~/.xilinx-rag/config.json

环境变量

变量

说明

XILINX_DOCS_ROOT

文档库根路径

HF_ENDPOINT

HuggingFace 镜像地址（国内设 https://hf-mirror.com）

架构

PDF / HTML 文件          Curl / Playwright（网页）
       │                        │
       ▼                        ▼
   parser.py              search_tools.py
   （pypdf2 解析）         （抓取+解析）
       │                        │
       ▼                        ▼
   ParsedChunk ────────► HybridRetriever.add_chunks()
                              │
               ┌──────────────┴──────────────┐
               ▼                              ▼
         SQLite FTS5                    ChromaDB
         （关键词索引）                  （向量嵌入）
               │                              │
               ▼                              ▼
       ┌─────────────────────────────────────────┐
       │  search() → RRF 融合                    │
       │  （FTS5 BM25 ∩ 向量余弦距离）            │
       └─────────────────────────────────────────┘
                              │
                              ▼
                      MCP 工具返回结果

存储

路径

大小（3000+ PDF）

说明

~/.xilinx-rag/corpus.db

~1.1 GB

SQLite — 文本语料 + FTS5 全文索引

~/.xilinx-rag/chroma_db/

~10.4 GB

ChromaDB — 向量嵌入（可选）

~/.xilinx-rag/file_hashes.json

~500 KB

已索引文件 SHA-256

~/.xilinx-rag/config.json

~100 B

用户配置

技术栈

组件

库

用途

MCP 框架

mcp >= 1.0.0（FastMCP）

MCP 服务器生命周期

关键词搜索

SQLite FTS5（内建）

全文检索 + BM25 排序

向量存储

chromadb >= 0.5

持久化向量嵌入

嵌入模型

sentence-transformers >= 3.0

BAAI/bge-small-zh-v1.5（512 维）

PDF 解析

pypdf2 >= 3.0

PDF 文本提取

HTML 解析

beautifulsoup4 >= 4.12、lxml >= 5.0

网页内容提取

浏览器

playwright >= 1.40

JS 渲染 + PDF 导出

构建

hatchling

PEP 621 wheel 构建

搜索性能

指标

值

首次搜索（含模型加载）

~28 秒

后续搜索（模型已驻内存）

<500 ms

FTS5 索引重建

~29 秒

向量嵌入重建（3000+ PDF）

~5 小时（CPU）

索引存储总量

~12 GB

许可证

未指定。

This server cannot be installed

F
license - not found
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Can-Y/doc_search'

If you have feedback or need assistance with the MCP directory API, please join our Discord server