使用说明
多语言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
