Vector Roam MCP

多语言MCP生态系统：语义知识检索

该存储库记录了混合 模型上下文协议（MCP） 设计用于将结构化本地笔记（Org-roam/Anytype）与高性能语义检索连接起来的架构 Qdrant.

🏗️ 项目结构

为了保持关注点的清晰分离，该项目组织如下：

.
├── docker-compose.yml         # Qdrant persistence layer
├── flake.nix                  # Unified NixOS development environment
├── flake.lock
├── python_notes_server/       # Python MCP Server (Notes management)
│   ├── main.py
│   ├── pyproject.toml
│   └── uv.lock
└── rust_vector_engine/        # Rust MCP Server (Embeddings & Qdrant)
    ├── Cargo.toml
    └── src/
        └── main.rs

核心概念：向量搜索和潜在表示

以下理论框架指导本项目的工程决策。

1.嵌入和潜在空间

人工智能模型不“使用”矢量搜索；它们执行特征提取以生成嵌入。该过程通过推理将非结构化数据（文本、图像、音频）映射到高维潜在空间（流形）中。

“本质”：每个向量都是一个固定长度的浮点数列表。“概念本质”只是这个空间内数据点的坐标。

不可解释性：维度是潜在的，这意味着它们没有人类可读的名称，如“毛茸茸的”或“国内的”。这个含义分布在整个向量上。

2.上下文映射（分布语义学）

模型通过分布假说学习：出现在相似语境中的单词具有相似的含义。

• 他们不“理解”森林；他们计算出森林、树木和绿色具有很高的共现概率。
• 映射过程将这些相关的令牌聚集在潜在空间的同一邻域中。

3.向量算术和语义关系

空间组织允许线性关系映射。因为关系被编码为方向和距离（偏移），所以我们可以对概念执行算术运算：

• *逻辑：*

$$\\vec{v}_{\\text{bark}\\approach\\vec{v}_{\\text{meow}}+（\\vec{v}_{\\text{dog}-\\vec{v}_{\\text{cat}}）$$

• 术语($\vec{v}_{\text{meow}} \\- \vec{v}_{\text{cat}}$）是“声音到物种”的抵消。将其添加到$\\vec{v}\_{\\text{dog}}$将我们移动到该物种的相应声音。

4.困惑和统计异常

在短语“我的猫吠叫”中，模型不是通过逻辑，而是通过统计距离来检测异常。

• 在训练语料库中，猫向量和树皮向量之间的转换概率接近零。

• 该模型感知到高度的困惑：序列在数学上是“出乎意料的”，因为向量位于流形的遥远、不相关的区域。

5.检索与推理

区分编码器和矢量数据库至关重要：

• *编码器（LLM/变压器）：* 接收输入并生成向量（推理）。

• *矢量数据库（Qdrant）：* 存储数百万个向量并执行搜索。

• *度量标准：* 它使用余弦相似度来测量查询向量和存储向量之间的角度接近度，而不是精确的关键字匹配：

$$\\text{cosine\\\_sim}（\\mathbf{A}，\\mathbf{1B}）=\\frac{\\mathbf{0}\\cdot\\mathbf}{|\\mathbf\[A}||\\mathbf{B}|}$$

6.搜索优化（ANN）

对于海量数据集，计算每个向量的距离在计算上很昂贵（$O（n）$）。工程解决方案使用近似最近邻（ANN）算法，如HNSW（分层导航小世界），在对数时间内找到“最接近”的概念。

______________________________________________________________________

技术栈

• 语言：Python 3.13（Notes Logic），Rust（矢量引擎）。

• 环境：NixOS和flake.nix用于可重复构建。

• 数据库：Qdrant（矢量数据库）。

• 包管理：uv（Python），cargo（Rust）。

• 协议：模型上下文协议（MCP）。

______________________________________________________________________

入门指南

1.环境设置

确保您使用的是启用薄片的Nix。

nix develop

2.基础设施

启动本地Qdrant实例：

docker compose up -d

3.运行MCP服务器

要在开发过程中调试和检查服务器，请使用MCP检查器。

对于Python服务器：

cd python_notes_server
uv run mcp dev main.py

对于rust服务器：

cd rust_vector_engine
cargo build
mcp dev ./target/debug/rust_vector_engine