groundkit Skill 技能

技能简介

groundkit 是由独立开发者 Andy Freeman 构建的本地优先检索引擎，核心特性是答案附带可验证引用，每一个搜索结果都会指向源文档的精确字符位置，并自动核验该引用是否真实存在于原文件中，从而彻底杜绝大模型幻觉导致的「无中生有」回答。最新版本 v0.2.1 发布于 2026 年 9 月 23 日，集 BM25 关键词检索、稠密向量混合检索、可信度评估套件和 MCP 服务器于一身，无需任何云端凭证即可完整运行，是当前开源生态中引用可验证性做得最彻底的 RAG 底层组件。

核心能力

1. 引用可验证检索：每次搜索结果的每一条目都附带源文件路径 + 精确字符偏移（citation），工具会自动 re-read 源文件确认引用文本确实存在，而非仅凭模型「自信宣称」。
2. BM25 + 稠密向量混合检索：默认 BM25 模式零依赖外部服务；开启 --dense 后可接入 Ollama 等本地 Embedding 提供者，通过倒数排名融合（RRF）合并两种检索路径，实测在所有指标上均优于纯 BM25 基线。
3. 本地跨编码重排序：可选的 rerank 扩展提供本地 Cross-Encoder 重排序，对 Top 结果进行更精确的二次评分。
4. 检索质量可量化评估：内置 Eval Harness，以固定测试语料 + 已知答案（golden corpus / judgment set）为基准，自动计算 Recall@K、MRR、nDCG@K 等指标，并支持接入 BEIR 公开评测数据集进行扩展评估。
5. 标准 MCP 服务器接口：通过 grk serve-mcp 启动 MCP 服务（Stdio + Streamable HTTP），向 Claude Desktop / Claude Code 等 AI 助手暴露 search、fetch_chunk、list_collections、index_status 工具，天然集成 Agent 工作流。
6. 增量索引与持久化存储：文档摄取后内容哈希比对，变更文件才重新索引；SQLite + Lance 双存储引擎，进程重启后索引不丢失。
7. LLM 边界严格管控：检索路径无任何 LLM 调用；云端对话出口统一经过去标识化处理（Redaction Pass），Embedding 边界为明确声明的可信例外，不存在隐性数据泄露。

安装配置

环境要求

• Python 3.11+
• 推荐使用 uv 包管理器（项目大量使用 uv run 作为标准调用方式）
• 若启用稠密检索，需本地运行 Ollama 并拉取 Embedding 模型

安装步骤

方式一：pip 直接安装（推荐）

pip install groundkit

方式二：从源码克隆开发安装

git clone https://github.com/tafreeman/groundkit.git
cd groundkit
uv sync --group dev    # 安装开发依赖
uv run grk --help      # 验证安装

方式三：Docker 部署（含完整观测栈） 项目仓库提供 docker-compose.yml，内置 OpenTelemetry Collector + Jaeger，适用于希望以容器化方式运行 MCP 服务器和 REST API 的场景。

Ollama Embedding 配置（可选，启用混合检索时必需）

ollama pull nomic-embed-text   # 拉取默认 Embedding 模型（可替换为任意 Ollama 支持模型）

使用步骤

第一步：摄取文档建立索引

# 仅 BM25（默认，零依赖）
grk ingest ./docs

# 稠密向量模式（需 Ollama 运行中）
grk ingest ./docs --dense --collection my_corpus

# 摄取网络 URL（自动快照到本地，带 SSRF 防护）
grk ingest https://example.com/doc --collection web_docs

索引增量写入，.groundkit/ 目录持久化存储，进程重启不丢失。

第二步：执行检索查询

# 标准检索（返回带引用的结果）
grk search "你的查询内容"

# JSON 格式输出（便于程序解析）
grk search "你的查询内容" --json

# 混合检索模式（需稠密索引）
grk search "你的查询内容" --mode hybrid --collection dense

每个结果均包含 source（文件路径）、start / end（字符偏移），即完整 citation，可供下游 groundkit.retrieval.verify_citation() 核验。

第三步：启动 MCP 服务接入 AI 助手

# 启动 MCP 服务器（Stdio 模式，Claude Desktop 推荐）
grk serve-mcp

# 或启动 REST API（适用于远程调用场景）
grk serve --host 0.0.0.0 --port 7777

在 Claude Desktop 配置中新增 MCP 服务器，指向本地编译后的二进制，即可通过自然语言直接检索私有文档库。

第四步：运行检索质量评估

# 使用内置 Golden Corpus 评估当前检索配置
uv run grk eval

# 使用 BEIR 数据集自定义评估
uv run grk eval --corpus-dir /path/to/beir/corpus --judgments /path/to/judgments.jsonl

# 对比两次评估结果的统计显著性
python -c "from groundkit.evals.significance import compare; print(compare('results/run_a.json','results/run_b.json'))"

评估报告输出至 evals/results/latest.json，BM25 为所有新功能的强制基线（报告须显示优于 BM25 基线，否则如实报告）。

适用场景

1. 企业内部知识库问答：将产品文档、API 手册、合规文件摄取为本地索引，Claude Code/Desktop 接入 MCP 后可精确回答「这条政策在哪一页的哪一段」，而非泛泛而谈。
2. AI 编程助手文档检索：将项目 ARCHITECTURE.md、API 文档、测试规范纳入索引，让 AI 在修改代码时能够引用真实的项目约束而非凭记忆「脑补」。
3. 法律 / 医疗 / 金融等高可信度要求场景：引用必须可验证，任何幻觉性回答在引用核验阶段即被发现，适用于需要精确条文依据的专业领域。
4. RAG 系统开发与评测：内置 Eval Harness 提供量化指标，开发者可系统对比 BM25 / 混合检索 / 重排序不同配置的效果，而非靠主观感受判断改进是否真实。
5. 私有代码库语义搜索：将代码仓库文档化后建立索引，结合 Claude 的代码理解能力，实现语义级别的代码搜索和修改建议。
6. 科研文献管理与问答：配合 URL 摄取功能，将 arXiv、PubMed 等来源的文献纳入本地索引，提问时附带文献内精确引用。

适用人群

• AI 应用开发者：需要构建引用可验证的 RAG 系统，而非仅依赖模型「自信度」判断答案可靠性。
• 企业知识管理团队：需要在私有环境中部署文档检索能力，不接受数据上传至第三方云服务。
• AI 编程助手重度用户：希望 Claude Code / Cursor 等工具能够精确引用项目内文档，而非凭记忆回答。
• 检索系统研究人员：需要一个可量化、可复现的本地评测基准，对比不同检索策略的实际效果。
• 安全敏感型团队：关注 LLM 应用中的数据边界管控，需要明确知道哪些文本何时以何种方式离开本地环境。

工作原理

groundkit 的设计哲学是确定性核心 + LLM 仅在边界。具体架构如下：

摄取阶段（Ingest）：文档被切分为固定策略的文本块（Chunking），每个块写入 SQLite（BM25 元数据）和 Lance（稠密向量）双索引，块级别记录文件路径和字符偏移构成引用信息。URL 摄取通过 SSRF 防护将远程内容快照到本地，确保引用始终可重新核验。

检索阶段（Retrieve）：BM25 路径由 Okapi BM25 算法实现，完全确定性，无 LLM 调用；稠密路径通过本地 Ollama Embedding 模型生成向量，余弦相似度评分；两条路径的结果通过 Reciprocal Rank Fusion（RRF）合并为最终排序。Cross-Encoder 重排序作为可选的第二阶段进一步提升精度。

引用核验（Verify）：每个结果返回的 citation（含文件路径和字符偏移）通过 groundkit.retrieval.verify_citation() 重新读取源文件、截取对应字符段，与检索返回的块内容做逐字比对，不一致时降权或剔除。这是最关键的可信度保障环节——模型给出的「答案」必须物理上存在于源文档中。

合成阶段（Synthesize）：LLM 仅出现在检索后的答案合成环节，且云端对话出口统一经过 Redaction Pass，去除敏感信息后再发出。Embedding 方向为明确声明的可信例外（文档明确说明），需用户自行确认 Ollama 实例的安全性。

评估机制（Eval）：Golden Corpus 由固定文档集 + 人工标注的问答对构成，BM25 作为强制基线，任何新功能须在相同测试条件下优于基线才可宣称为改进。Significance 模块使用配对 Bootstrap 计算置信区间，报告结果为区间而非点估计。

官方链接

• PyPI 包页面：https://pypi.org/project/groundkit/
• GitHub 仓库：https://github.com/tafreeman/groundkit
• 在线文档：https://tafreeman.github.io/groundkit/
• MCP 集成指南：https://tafreeman.github.io/groundkit/guides/mcp/
• Python 版本支持：3.11+
• 许可证：MIT
• 最新版本：v0.2.1（2026-09-23）