⚡

向量数据库应用技能Skill using-vector-databases

这个技能专注于使用向量数据库来实现人工智能和机器学习应用，包括语义搜索、检索增强生成（RAG）系统、推荐系统等。关键技术涵盖向量数据库选择（如Qdrant、Pinecone）、嵌入模型（如OpenAI、Voyage AI）、文档分块策略和混合搜索模式。适用于构建聊天机器人、搜索引擎、知识库问答等AI驱动的应用，关键词包括：向量数据库、AI、ML、语义搜索、RAG、嵌入生成、分块、混合搜索、Qdrant、Pinecone。

RAG应用 0 次安装 0 次浏览 更新于 3/23/2026

名称: 使用向量数据库 描述: 为AI/ML应用、语义搜索和RAG系统实现的向量数据库。适用于构建聊天机器人、搜索引擎、推荐系统或基于相似性的检索。涵盖Qdrant（主要）、Pinecone、Milvus、pgvector、Chroma、嵌入生成（OpenAI、Voyage、Cohere）、分块策略和混合搜索模式。

向量数据库在AI应用中的应用

何时使用此技能

在实现以下内容时使用此技能：

  • RAG（检索增强生成） 系统的AI聊天机器人
  • 语义搜索 功能（基于含义，不仅仅是关键词）
  • 基于相似性的推荐系统
  • 多模态AI（跨文本、图像、音频的统一搜索）
  • 文档相似性和去重
  • 在私有知识库上的问答

快速决策框架

1. 向量数据库选择

开始: 选择向量数据库

现有基础设施？
├─ 已经使用PostgreSQL？
│  └─ pgvector（<1000万个向量，预算紧张）
│      参见: references/pgvector.md
│
└─ 没有现有向量数据库？
   │
   ├─ 操作偏好？
   │  │
   │  ├─ 仅零操作托管
   │  │  └─ Pinecone（完全托管，卓越的开发者体验）
   │  │      参见: references/pinecone.md
   │  │
   │  └─ 灵活（自托管或托管）
   │     │
   │     ├─ 规模: <1亿个向量 + 复杂过滤 ⭐
   │     │  └─ Qdrant（推荐）
   │     │      • 最佳元数据过滤
   │     │      • 内置混合搜索（BM25 + 向量）
   │     │      • 自托管: Docker/K8s
   │     │      • 托管: Qdrant Cloud
   │     │      参见: references/qdrant.md
   │     │
   │     ├─ 规模: >1亿个向量 + GPU加速
   │     │  └─ Milvus / Zilliz Cloud
   │     │      参见: references/milvus.md
   │     │
   │     ├─ 嵌入式/无服务器
   │     │  └─ LanceDB（无服务器，边缘部署）
   │     │
   │     └─ 本地原型开发
   │        └─ Chroma（简单API，内存中）

2. 嵌入模型选择

需求？

├─ 最佳质量（成本不计）
│  └─ Voyage AI voyage-3（1024维）
│      • 在MTEB上比OpenAI好9.74%
│      • 约$0.12/100万令牌
│      参见: references/embedding-strategies.md
│
├─ 企业可靠性
│  └─ OpenAI text-embedding-3-large（3072维）
│      • 行业标准
│      • 约$0.13/100万令牌
│      • 维度缩短: 减少到256/512/1024维
│
├─ 成本优化
│  └─ OpenAI text-embedding-3-small（1536维）
│      • 约$0.02/100万令牌（便宜6倍）
│      • 大模型性能的90-95%
│
├─ 多语言（100多种语言）
│  └─ Cohere embed-v3（1024维）
│      • 约$0.10/100万令牌
│
└─ 自托管/隐私关键
   ├─ 英语: nomic-embed-text-v1.5（768维，Apache 2.0）
   ├─ 多语言: BAAI/bge-m3（1024维，MIT）
   └─ 长文档: jina-embeddings-v2（768维，8K上下文）

核心概念

文档分块策略

推荐大多数RAG系统的默认设置：

  • 分块大小： 512个令牌（不是字符）
  • 重叠： 50个令牌（10%重叠）

为什么这些数字？

  • 512个令牌平衡了上下文与精确性
    • 太小（128-256）：概念碎片化，失去上下文
    • 太大（1024-2048）：稀释相关性，浪费LLM令牌
  • 50个令牌重叠确保句子不在上下文中分裂

参见references/chunking-patterns.md以获取按内容类型的高级策略。

混合搜索（向量 + 关键词）

混合搜索 = 向量相似性 + BM25关键词匹配

用户查询: "OAuth刷新令牌实现"
           │
    ┌──────┴──────┐
    │             │
向量搜索        关键词搜索
（语义）        （BM25）
    │             │
前20个文档     前20个文档
    │             │
    └──────┬──────┘
           │
   互惠排名融合
   （合并 + 重新排序）
           │
    最终前5个结果

为什么混合搜索重要：

  • 向量捕获语义含义（“OAuth刷新” ≈ “令牌续订”）
  • 关键词确保精确匹配（"refresh_token"字面意思）
  • 结合提供最佳检索质量

参见references/hybrid-search.md以获取实现细节。

入门指南

Python + Qdrant示例

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct

# 1. 初始化客户端
client = QdrantClient("localhost", port=6333)

# 2. 创建集合
client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(size=1024, distance=Distance.COSINE)
)

# 3. 插入带有嵌入的文档
points = [
    PointStruct(
        id=idx,
        vector=embedding,  # 来自OpenAI/Voyage等
        payload={
            "text": chunk_text,
            "source": "docs/api.md",
            "section": "Authentication"
        }
    )
    for idx, (embedding, chunk_text) in enumerate(chunks)
]
client.upsert(collection_name="documents", points=points)

# 4. 使用元数据过滤搜索
results = client.search(
    collection_name="documents",
    query_vector=query_embedding,
    limit=5,
    query_filter={
        "must": [
            {"key": "section", "match": {"value": "Authentication"}}
        ]
    }
)

完整示例见examples/qdrant-python/。

TypeScript + Qdrant示例

import { QdrantClient } from '@qdrant/js-client-rest';

const client = new QdrantClient({ url: 'http://localhost:6333' });

// 创建集合
await client.createCollection('documents', {
  vectors: { size: 1024, distance: 'Cosine' }
});

// 插入文档
await client.upsert('documents', {
  points: chunks.map((chunk, idx) => ({
    id: idx,
    vector: chunk.embedding,
    payload: {
      text: chunk.text,
      source: chunk.source
    }
  }))
});

// 搜索
const results = await client.search('documents', {
  vector: queryEmbedding,
  limit: 5,
  filter: {
    must: [
      { key: 'source', match: { value: 'docs/api.md' } }
    ]
  }
});

完整示例见examples/typescript-rag/。

RAG管道架构

完整管道组件

1. 摄取
   ├─ 文档加载（PDF、网页、代码、Office）
   ├─ 文本提取与清理
   ├─ 分块（语义、递归、代码感知）
   └─ 嵌入生成（批处理、速率限制）

2. 索引
   ├─ 向量存储插入（批处理更新）
   ├─ 索引配置（HNSW、距离度量）
   └─ 关键词索引（用于混合搜索的BM25）

3. 检索（查询时间）
   ├─ 查询处理（扩展、嵌入）
   ├─ 混合搜索（向量 + 关键词）
   ├─ 过滤与后处理（元数据、MMR）
   └─ 重新排序（交叉编码器、基于LLM）

4. 生成
   ├─ 上下文构建（格式化分块、引用）
   ├─ 提示工程（系统 + 上下文 + 查询）
   ├─ LLM推理（流式、温度调优）
   └─ 响应后处理（引用、验证）

5. 评估（生产关键）
   ├─ 检索指标（精确度、召回率、相关性）
   ├─ 生成指标（忠实度、正确性）
   └─ 系统指标（延迟、成本、满意度）

生产RAG的必需元数据

过滤和相关性关键：

metadata = {
    # 源跟踪
    "source": "docs/api-reference.md",
    "source_type": "documentation",  # 代码、文档、日志、聊天
    "last_updated": "2025-12-01T12:00:00Z",

    # 层次上下文
    "section": "Authentication",
    "subsection": "OAuth 2.1",
    "heading_hierarchy": ["API Reference", "Authentication", "OAuth 2.1"],

    # 内容分类
    "content_type": "code_example",  # 散文、代码、表格、列表
    "programming_language": "python",

    # 过滤维度
    "product_version": "v2.0",
    "audience": "enterprise",  # 免费、专业、企业

    # 检索提示
    "chunk_index": 3,
    "total_chunks": 12,
    "has_code": True
}

为什么元数据重要：

  • 在向量搜索前启用过滤（减少搜索空间）
  • 通过目标检索提高相关性
  • 支持多租户系统（按用户/组织过滤）
  • 支持版本化文档（按产品版本过滤）

使用RAGAS评估

使用scripts/evaluate_rag.py进行自动化评估：

from ragas import evaluate
from ragas.metrics import (
    faithfulness,       # 答案基于上下文
    answer_relevancy,   # 答案回答查询
    context_recall,     # 检索的文档覆盖真实情况
    context_precision   # 检索的文档相关
)

# 测试数据集
test_data = {
    "question": ["如何刷新OAuth令牌？"],
    "answer": ["使用/token和refresh_token授权..."],
    "contexts": [["OAuth刷新文档..."]],
    "ground_truth": ["POST到/token，grant_type=refresh_token"]
}

# 评估
results = evaluate(test_data, metrics=[
    faithfulness,
    answer_relevancy,
    context_recall,
    context_precision
])

# 生产目标：
# faithfulness: >0.90（最小幻觉）
# answer_relevancy: >0.85（回答用户查询）
# context_recall: >0.80（检索到足够上下文）
# context_precision: >0.75（最小噪音）

性能优化

嵌入生成

  • 批处理： 每批100-500个分块
  • 缓存： 按内容哈希缓存嵌入
  • 速率限制： 遵守API提供商限制（指数退避）

向量搜索

  • 索引类型： 大多数情况使用HNSW（分层可导航小世界）
  • 距离度量： 标准化嵌入使用余弦
  • 预过滤： 在向量搜索前应用元数据过滤器
  • 结果多样性： 使用MMR（最大边际相关性）减少冗余

成本优化

  • 嵌入模型： 考虑text-embedding-3-small以应对预算约束
  • 维度减少： 使用维度缩短（3072维 → 1024维）
  • 缓存： 为重复查询实现语义缓存
  • 批操作： 分组插入/更新以提高效率

常见工作流

1. 构建RAG聊天机器人

  • 向量数据库：Qdrant（自托管或云）
  • 嵌入：OpenAI text-embedding-3-large
  • 分块：512个令牌，50重叠，语义分割器
  • 搜索：混合（向量 + BM25）
  • 集成：前端与ai-chat技能

完整实现见examples/qdrant-python/。

2. 语义搜索引擎

  • 向量数据库：Qdrant或Pinecone
  • 嵌入：Voyage AI voyage-3（最佳质量）
  • 分块：内容类型特定（见chunking-patterns.md）
  • 搜索：混合与重新排序
  • 过滤：按元数据预过滤（日期、类别等）

3. 代码搜索

  • 向量数据库：Qdrant
  • 嵌入：OpenAI text-embedding-3-large
  • 分块：基于AST（函数/类边界）
  • 元数据：语言、文件路径、导入
  • 搜索：混合与语言过滤

代码特定实现见examples/qdrant-python/。

与其他技能的集成

前端技能

  • ai-chat： 向量数据库驱动聊天界面背后的RAG管道
  • search-filter： 用语义搜索替换关键词搜索
  • data-viz： 可视化嵌入空间、相似性分数

后端技能

  • databases-relational： 使用pgvector扩展的混合方法
  • api-patterns： 通过REST/GraphQL暴露语义搜索
  • observability： 监控嵌入质量和检索指标

多语言支持

Python（主要）

  • 客户端：qdrant-client
  • 框架：LangChain, LlamaIndex
  • 参见：examples/qdrant-python/

Rust

  • 客户端：qdrant-client（在Context7中有1,549个代码片段）
  • 框架：原始Rust用于性能关键系统
  • 参见：examples/rust-axum-vector/

TypeScript

  • 客户端：@qdrant/js-client-rest
  • 框架：LangChain.js，与Next.js集成
  • 参见：examples/typescript-rag/

Go

  • 客户端：qdrant-go
  • 用例：高性能微服务

故障排除

检索质量差

  1. 检查分块策略（太大/太小？）
  2. 验证元数据过滤（太限制？）
  3. 尝试混合搜索而不是仅向量
  4. 实施重新排序阶段
  5. 使用RAGAS指标评估

性能慢

  1. 使用HNSW索引（不是Flat）
  2. 向量搜索前用元数据预过滤
  3. 减少向量维度（维度缩短）
  4. 批处理操作（插入、搜索）
  5. 考虑GPU加速（Milvus）

成本高

  1. 切换到text-embedding-3-small
  2. 实现语义缓存
  3. 减少分块重叠
  4. 使用自托管嵌入（nomic, bge-m3）
  5. 批处理嵌入生成

Qdrant Context7文档

主要资源： /llmstxt/qdrant_tech_llms-full_txt

  • 信任分数： 高
  • 代码片段： 10,154
  • 质量分数： 83.1

通过Context7访问：

resolve-library-id({ libraryName: "Qdrant" })
get-library-docs({
  context7CompatibleLibraryID: "/llmstxt/qdrant_tech_llms-full_txt",
  topic: "hybrid search collections python",
  mode: "code"
})

额外资源

参考文档

  • references/qdrant.md - 全面的Qdrant指南
  • references/pgvector.md - PostgreSQL pgvector扩展
  • references/milvus.md - 亿级规模的Milvus/Zilliz
  • references/embedding-strategies.md - 嵌入模型比较
  • references/chunking-patterns.md - 高级分块技术

代码示例

  • examples/qdrant-python/ - FastAPI + Qdrant RAG管道
  • examples/pgvector-prisma/ - PostgreSQL + Prisma集成
  • examples/typescript-rag/ - TypeScript RAG与Hono

自动化脚本

  • scripts/generate_embeddings.py - 批处理嵌入生成
  • scripts/benchmark_similarity.py - 性能基准测试
  • scripts/evaluate_rag.py - RAGAS基于评估

下一步：

  1. 根据规模和基础设施选择向量数据库
  2. 基于质量与成本权衡选择嵌入模型
  3. 为内容类型实施分块策略
  4. 设置混合搜索以用于生产质量
  5. 使用RAGAS指标评估
  6. 优化性能和成本