Vector Db Manager Free

管理本地与云端向量数据库的索引创建、嵌入导入和相似度检索，支持PostgreSQL pgvector、Milvus、ChromaDB等引擎。

向量数据库管理工具（免费版）

概述

本Skill帮助AI应用开发者管理向量数据库的完整生命周期。从索引创建到嵌入向量导入，从相似度检索到基础性能调优，覆盖向量数据管理的核心环节。

免费版支持单机部署的向量数据库管理，适合原型验证与中小规模应用（百万级向量以下）。

核心能力

能力模块	说明	免费版支持
索引创建与管理	创建/删除/重建向量索引	是
嵌入向量导入	单条/批量导入向量数据	是（批量上限1万）
KNN精确检索	K近邻精确相似度检索	是
ANN近似检索	近似最近邻检索	是（基础算法）
集合与分区管理	创建/删除集合与分区	是
基础统计信息	向量数量/维度/索引大小	是
多引擎适配	PostgreSQL pgvector/Milvus/ChromaDB	是
混合检索	向量+标量联合检索	否（专业版）
多副本与分片	分布式部署管理	否（专业版）
性能优化引擎	索引参数自动调优	否（专业版）

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：管理向量数据库的、嵌入与相似度检索、支持本地与云端部、应用开发者的向量、数据库管理工具、覆盖向量索引创建、嵌入向量管理、相似度检索与基础、性能调优、核心能力、创建与删除向量索、批量导入嵌入向量、管理集合与分区、查询基础统计信息、Use、when、需要数据库操作、数据存储管理时使、不适用于数据库架、构设计决策等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：语义搜索引擎

某文档平台需要实现"按语义搜索而非关键词匹配"的搜索功能。通过本Skill创建向量索引，将文档嵌入向量导入数据库，用户搜索时将查询文本转为向量并执行相似度检索。

场景二：推荐系统

某内容平台基于用户兴趣向量与内容向量计算相似度，推荐最相关的内容。通过本Skill管理用户画像向量与内容向量，执行实时相似度检索。

常见问题

某客服系统将知识库文档转为向量存储，用户提问时检索最相关的文档片段，结合LLM生成回答。通过本Skill管理知识库向量索引。

快速开始

第一步：选择向量数据库引擎（约30秒）

引擎	适用场景	免费版支持
PostgreSQL + pgvector	已有PG环境，中小规模	是
Milvus	大规模向量，高性能	是（单机模式）
ChromaDB	轻量级，快速原型	是
Qdrant	Rust实现，高性能	是

第二步：创建向量索引

python

# 示例
# 依赖说明
CREATE EXTENSION IF NOT EXISTS vector;
# ...
# 创建带向量字段的表
CREATE TABLE documents (
    id BIGSERIAL PRIMARY KEY,
    content TEXT,
    embedding vector(1536),  # OpenAI text-embedding-ada-002维度
    metadata JSONB
);
# ...
# 创建HNSW索引（推荐，查询速度快）
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
    WITH (m = 16, ef_construction = 64);
# ...
# 或创建IVFFLAT索引（构建速度快，适合初始阶段）
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops)
    WITH (lists = 100);

第三步：导入嵌入向量

python

import psycopg2
# ...
conn = psycopg2.connect("postgresql://user:pass@localhost/db")
cur = conn.cursor()
# ...
# 批量导入向量数据
vectors = [
    ("文档内容1", [0.1, 0.2, ...], {"source": "web"}),
    ("文档内容2", [0.3, 0.4, ...], {"source": "pdf"}),
]
# ...
from psycopg2.extras import execute_values
execute_values(
    cur,
    "INSERT INTO documents (content, embedding, metadata) VALUES %s",
    [(c, e, m) for c, e, m in vectors]
)
conn.commit()

第四步：执行相似度检索

sql

-- 查询与给定向量最相似的10条文档
SELECT id, content, metadata,
    1 - (embedding <=> '[0.1, 0.2, ...]') AS similarity
FROM documents
ORDER BY embedding <=> '[0.1, 0.2, ...]'
LIMIT 10;
# ...
-- 带标量过滤的检索
SELECT id, content,
    1 - (embedding <=> '[0.1, 0.2, ...]') AS similarity
FROM documents
WHERE metadata->>'source' = 'web'
    AND 1 - (embedding <=> '[0.1, 0.2, ...]') > 0.8
ORDER BY embedding <=> '[0.1, 0.2, ...]'
LIMIT 10;

响应解析: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤。

配置示例

索引类型选择决策

索引类型	构建速度	查询速度	召回率	内存占用	推荐场景
HNSW	慢	极快	高	高	查询频繁，数据量中等
IVFFLAT	快	中	中	低	数据量大，可接受部分召回损失
Flat（暴力）	无需构建	慢	100%	低	数据量小（<10万），需精确结果

向量维度参考

嵌入模型	维度	适用场景
OpenAI text-embedding-3-small	1536	通用文本嵌入
OpenAI text-embedding-3-large	3072	高精度需求
BGE-base-zh	768	中文文本
BGE-large-zh	1024	中文高精度
Sentence-BERT	384	轻量级英文
Cohere embed-v3	1024	多语言

距离度量选择

度量方式	公式	适用场景	pgvector操作符
余弦相似度	1 - cos(θ)	文本语义相似	<=>
欧氏距离	L2范数	图像特征	<->
内积	点积	归一化后的相似度	<#>

ChromaDB配置示例

python

import chromadb
# ...
client = chromadb.PersistentClient(path="./vector_db")
# ...
# 创建集合
collection = client.create_collection(
    name="documents",
    metadata={"hnsw:space": "cosine"}  # 使用余弦距离
)
# ...
# 批量添加向量
collection.add(
    ids=["doc1", "doc2"],
    documents=["文档内容1", "文档内容2"],
    embeddings=[[0.1, 0.2], [0.3, 0.4]],
    metadatas=[{"source": "web"}, {"source": "pdf"}]
)
# ...
# 相似度检索
results = collection.query(
    query_embeddings=[[0.15, 0.25]],
    n_results=10,
    where={"source": "web"}
)

最佳实践

批量导入优化

python

# 推荐：使用批量插入而非逐条插入
BATCH_SIZE = 1000  # 每批1000条
# ...
def batch_import(vectors, conn):
    cur = conn.cursor()
    for i in range(0, len(vectors), BATCH_SIZE):
        batch = vectors[i:i+BATCH_SIZE]
        execute_values(
            cur,
            "INSERT INTO documents (content, embedding, metadata) VALUES %s",
            batch
        )
        conn.commit()
        print(f"已导入 {min(i+BATCH_SIZE, len(vectors))}/{len(vectors)}")

索引参数调优

参数	作用	推荐值	说明
m（HNSW）	每层连接数	16-48	越大召回越高，内存越多
ef_construction	构建时搜索宽度	64-256	越大构建越慢，质量越好
ef_search	查询时搜索宽度	40-128	越大查询越慢，召回越高
lists（IVFFLAT）	聚类中心数	sqrt(N)	N为向量总数

错误恢复策略

错误类型	原因	恢复策略
维度不匹配	嵌入模型与索引维度不一致	重建索引或更换嵌入模型
内存不足	HNSW索引占用过大	切换IVFFLAT或减少m值
查询超时	ef_search过大或数据量过大	降低ef_search，添加标量过滤
导入失败	批量过大或格式错误	减小batch_size，检查向量格式
索引膨胀	频繁删除导致	定期REINDEX重建索引

常见问题(补充)

Q1：应该选择哪个向量数据库引擎？

A：根据规模和现有技术栈选择：(1) 已有 PostgreSQL 且向量数<100万，选pgvector；(2) 需要高性能且向量数>100万，选Milvus；(3) 快速原型验证，选ChromaDB；(4) 追求极致性能，选Qdrant。

Q2：HNSW和IVFFLAT怎么选？

A：HNSW查询更快但构建慢、内存占用高，适合查询频繁的场景。IVFFLAT构建快、内存占用低，但查询速度和召回率略低，适合数据量大且可接受部分召回损失的场景。

Q3：向量维度对性能有什么影响？

A：维度越高，存储空间和计算成本越大。1536维向量比768维多消耗一倍存储。建议根据实际需求选择合适维度的嵌入模型，不必一味追求高维度。

已知限制

A：免费版不限制使用次数，但批量导入上限为1万条/次，不支持混合检索（向量+标量联合排序）、多副本分片部署、索引参数自动调优、向量数据版本管理等高级功能。

Q5：如何监控向量数据库性能？

A：免费版提供基础统计信息（向量数量、索引大小、查询延迟）。如需实时监控仪表盘、慢查询分析、容量规划等高级监控，请使用专业版。

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• Python: 3.8+
• 数据库: PostgreSQL 14+ / Milvus 2.0+ / ChromaDB 0.4+ / Qdrant 1.0+

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent平台内置LLM提供
pgvector	PG扩展	pgvector必需	CREATE EXTENSION vector
psycopg2	Python库	PG必需	pip install psycopg2-binary
pymilvus	Python库	Milvus必需	pip install pymilvus
chromadb	Python库	ChromaDB必需	pip install chromadb
qdrant-client	Python库	Qdrant必需	pip install qdrant-client
numpy	Python库	推荐	pip install numpy

API Key 配置

• 数据库连接串: 存储于环境变量 DATABASE_URL / VECTOR_DB_URL
• 嵌入模型API: OpenAI/Cohere等API密钥，存储于环境变量 EMBEDDING_API_KEY
• 禁止: 在代码或配置文件中硬编码密钥
• 推荐: 使用 .env 文件管理，并在 .gitignore 中排除

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent管理向量数据库

免费版限制

本免费体验版限制以下高级功能：

• 批量导入上限为1万条/次
• 不支持混合检索（向量相似度+标量排序联合检索）
• 不支持多副本与分片部署管理
• 不支持索引参数自动调优
• 不支持向量数据版本管理与回滚
• 不支持实时性能监控仪表盘
• 不提供优先技术支持

解锁全部功能请使用专业版：vector-db-manager-pro

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

示例

基本用法

输入：用户提供操作指令和必要参数

输出：返回执行结果,包含操作状态和输出数据

text

用户: 执行核心功能
Skill: 正在执行核心功能...
Skill: 执行完成,结果如下: 操作成功

输出格式

json

{
  "success": true,
  "data": {
    "result": "向量数据库管理免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "vector db manager"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}