人工智能个人知识库MCP
本文档概述了AI个人知识库MCP的设置、使用和配置，这是一个旨在管理您的长期记忆和知识库并与之交互的综合系统。它利用文本嵌入进行语义搜索、相似性比较，并在PostgreSQL数据库中使用Pgvector进行高效存储。
1.导言
AI个人知识库MCP是一个FastAPI应用程序，它利用句子转换器将文本转换为密集的数字向量（嵌入）。然后，这些嵌入可用于语义搜索、相似性比较和Pgvector等向量数据库中的聚类等任务。
2.特点
- 文本嵌入生成： 将输入文本转换为高维向量表示。
- 健康检查端点： 提供一个简单的端点来检查服务的状态和加载的模型。
- Pgvector集成： 旨在使用Pgvector扩展与PostgreSQL数据库无缝协作，以实现高效的向量存储和相似性搜索。
- SQL查询执行： 允许直接对内存数据库执行SQL查询。
- 内存相似性搜索： 便于根据文本输入搜索类似的内存记录。
- 内存CRUD操作： 支持创建、读取、更新和删除内存记录。
3.嵌入模型
该服务目前使用 all-mpnet-base-v2 句子转换器模型，它产生 768维 嵌入。
- 尺寸说明： 虽然该服务最初配置为使用
diwank/dfe-base-en-1模型中，该模型出现了“输入未指定任何键，allow_vempty_key为False”错误。通过将输入作为字典传递来解决这个问题[{"text": data.text}]到model.encode()然而为了更广泛的兼容性和稳定性，all-mpnet-base-v2（768维）目前正在使用中。
4.设置
先决条件
- Docker： 确保Docker已安装并在您的系统上运行。
- Gemini CLI： 与服务交互需要Gemini命令行界面。
- PostgreSQL与Pgvector： PostgreSQL数据库
pgvector已安装并启用扩展。
环境变量
在运行应用程序之前，您需要创建一个 .env 项目根目录中的文件，用于存储您的配置。
- 创建一个名为的文件
.env. - 将下面的模板复制到文件中，并用您的实际凭据替换占位符值。
.env 模板：
POSTGRES_HOST=your_postgres_host
POSTGRES_PORT=5432
POSTGRES_DATABASE=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secret_password变量描述：
POSTGRES_HOST：PostgreSQL服务器的主机名或IP地址（例如。，localhost或PgVectorDB).POSTGRES_PORT：PostgreSQL服务器运行的端口（默认为5432).POSTGRES_DATABASE：要连接的数据库的名称。POSTGRES_USER：PostgreSQL数据库的用户名。POSTGRES_PASSWORD：指定用户的密码。这应该保密。
Docker命令
按照以下步骤使用Docker构建和运行嵌入服务：
- 构建Docker镜像：
docker build -t embedding-mcp .此命令构建Docker映像并将其标记为 embedding-mcp.
- 运行Docker容器：
docker run -d --name embedding-mcp -p 8000:8000 embedding-mcp此命令以分离模式运行容器(-d)，命名它 embedding-mcp，并将容器的端口8000映射到主机上的端口8000。
- 停止Docker容器：
docker stop embedding-mcp- 移除Docker容器：
docker rm embedding-mcpPostgreSQL数据库设置
确保你的PostgreSQL数据库有 pgvector 启用了扩展，并配置了一个表来存储嵌入。这 memory 表在此上下文中使用：
- 启用Pgvector扩展：
CREATE EXTENSION IF NOT EXISTS vector;memory表架构：
这 memory 该表旨在存储长期内存条目。这 embedding 列对于相似性搜索至关重要。
CREATE TYPE memory_scope AS ENUM ('personal', 'project', 'global');
CREATE TYPE memory_category AS ENUM ('Code', 'Idea', 'Instruction', 'Fix', 'Doc', 'Other');
CREATE TABLE memory (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
content TEXT NOT NULL,
embedding VECTOR(768) NOT NULL, -- Current dimension is 768
scope memory_scope NOT NULL DEFAULT 'personal',
project TEXT,
category memory_category,
tags TEXT[],
source TEXT,
priority INTEGER DEFAULT 0,
status memory_status DEFAULT 'active',
usage_count INTEGER DEFAULT 0,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
last_used_at TIMESTAMP WITH TIME ZONE
);- 创建HNSW索引以进行相似性搜索：
为了高效地进行相似性搜索，应在以下位置创建HNSW（分层导航小世界）索引 embedding 列。这大大加快了涉及 `` （余弦距离）运算符。
CREATE INDEX ON memory USING hnsw (embedding vector_cosine_ops);5.API终点
人工智能个人知识库MCP公开了以下API端点：
5.1.GET/健康
- 说明： 检查服务的运行状况和状态，包括嵌入模型是否已加载。
- 答复：
{
"status": "ok",
"model_loaded": true,
"model_name": "all-mpnet-base-v2"
}5.2.POST/嵌入
- 说明： 为提供的输入文本生成高质量的文本嵌入。
- 请求正文（application/json）：
{
"text": "The string of text to generate an embedding for."
}- 响应（应用程序/json）：
{
"embedding": [0.1, 0.2, ..., 0.N], // N is the dimension of the embedding (e.g., 768)
"model": "all-mpnet-base-v2"
}5.3.POST/db_query
- 说明： 对连接的PostgreSQL数据库执行原始SQL查询。
- 请求正文（application/json）：
{
"query": "SELECT * FROM public.memory LIMIT 5;"
}- 响应（应用程序/json）：
- 对于 SELECT 查询：一个JSON对象数组，其中每个对象代表一行。 - 对于 INSERT, UPDATE, DELETE 查询：
{
"status": "success",
"rows_affected": 1
}5.4.POST/mem_相似性
- 说明： 在中执行相似性搜索
memory基于查询文本的表。它为查询文本生成一个嵌入，然后找到最相似的内存记录。 - 请求正文（application/json）：
{
"query_text": "Your search query here",
"top_k": 5
}- 响应（应用程序/json）： 一个JSON对象数组，每个对象代表一个类似的内存记录，并添加一个
similarity分数。
5.5.POST/mem_crud
- 说明： 在中插入新的内存记录或更新现有的内存记录
memory桌子。它会自动为content现场。 - 请求正文（application/json）：
{
"id": null, // Optional: Provide ID for update, omit for insert
"title": "My New Memory",
"content": "This is the content of my new memory.",
"scope": "personal",
"project": "AI_Personal_Knowledge_Base_MCP",
"category": "Idea",
"tags": ["AI", "memory"],
"source": "Gemini CLI",
"priority": 1,
"status": "active",
"usage_count": 0,
"created_at": null,
"updated_at": null,
"last_used_at": null
}- 响应（应用程序/json）：
- 插入：
{
"status": "success",
"id": 123,
"operation": "insert"
}- 更新：
{
"status": "success",
"id": 123,
"operation": "update",
"rows_affected": 1
}6.使用Gemini CLI
Gemini CLI通过定义的工具与嵌入服务交互。
生成嵌入
使用 generate_embedding_embed_post 为给定文本生成嵌入的工具：
print(default_api.generate_embedding_embed_post(text = "Your text here"))
执行相似性搜索
在您的数据库中执行相似性搜索 memory 表：
- 为您的查询生成嵌入：
print(default_api.generate_embedding_embed_post(text = "Your search query here"))
复制 embedding 从输出中提取数组。
- 执行SQL查询：
使用 execute_sql 使用生成的嵌入和 ` 余弦距离运算符。替换 [YOUR_QUERY_EMBEDDING]` 使用实际的嵌入阵列。
print(default_api.execute_sql(sql = "SELECT id, title, content, embedding ARRAY[YOUR_QUERY_EMBEDDING]::vector(768) AS similarity FROM postgres.public.memory ORDER BY similarity LIMIT 5;"))
*注：确保 postgres.public.memory 匹配您的数据库、模式和表名。*
7.故障排除
- “嵌入生成过程中出错：输入未指定任何键，allow_vempty_key为False”：此错误通常发生在
diwank/dfe-base-en-1模型需要一个类似字典的输入。修复涉及修改app.py将输入传递为[{"text": data.text}]到model.encode(). - 缓慢的相似性搜索： 如果相似性搜索速度较慢，请确保您已在您的
embedding列，如PostgreSQL设置部分所述。对于非常小的表，PostgreSQL可能不会使用索引，但随着数据的增长，它会变得有效。 - “未提供有效的会话ID”：此错误表示存在问题
FastApiMCP集成需要一个未提供的会话ID。这通常需要外部配置或绕过FastApiMCP用于直接工具调用。
8.Gemini CLI配置
要将嵌入服务与Gemini CLI一起使用，您需要配置 mcpServers 在你的 settings.json 文件。这允许CLI将工具调用路由到正在运行的Docker容器。
将以下配置添加到您的 settings.json:\`
"mcpServers": {
"MCP_DOCKER": {
"command": "docker",
"args": [
"mcp",
"gateway",
"run"
]
},
"embedding": {
"httpUrl": "http://localhost:8000/mcp"
}
}MCP_DOCKER：此条目定义了一个通过Docker运行MCP网关的命令。embedding：此条目指向嵌入服务的HTTP URL，使其工具可供Gemini CLI使用。
使用此配置，您可以调用 generate_embedding_embed_post 工具和其他工具直接从Gemini CLI嵌入服务。
9.未来的增强功能
- 批量嵌入生成： 实现嵌入生成的批处理，以提高处理多个文本输入时的效率。这将需要修改嵌入服务API以接受文本列表。
- 优化数据库插入： 探索将数据批量插入PostgreSQL数据库的更优化方法，例如使用
COPY命令或批处理INSERT声明。