using-vector-databases

AI 应用的向量数据库

何时使用此技能

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

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

快速决策框架

1. 向量数据库选择

START: Choosing a Vector Database

EXISTING INFRASTRUCTURE?
├─ Using PostgreSQL already?
│  └─ pgvector (<10M vectors, tight budget)
│      See: references/pgvector.md
│
└─ No existing vector database?
   │
   ├─ OPERATIONAL PREFERENCE?
   │  │
   │  ├─ Zero-ops managed only
   │  │  └─ Pinecone (fully managed, excellent DX)
   │  │      See: references/pinecone.md
   │  │
   │  └─ Flexible (self-hosted or managed)
   │     │
   │     ├─ SCALE: <100M vectors + complex filtering ⭐
   │     │  └─ Qdrant (RECOMMENDED)
   │     │      • Best metadata filtering
   │     │      • Built-in hybrid search (BM25 + Vector)
   │     │      • Self-host: Docker/K8s
   │     │      • Managed: Qdrant Cloud
   │     │      See: references/qdrant.md
   │     │
   │     ├─ SCALE: >100M vectors + GPU acceleration
   │     │  └─ Milvus / Zilliz Cloud
   │     │      See: references/milvus.md
   │     │
   │     ├─ Embedded / No server
   │     │  └─ LanceDB (serverless, edge deployment)
   │     │
   │     └─ Local prototyping
   │        └─ Chroma (simple API, in-memory)

2. 嵌入模型选择

REQUIREMENTS?

├─ Best quality (cost no object)
│  └─ Voyage AI voyage-3 (1024d)
│      • 9.74% better than OpenAI on MTEB
│      • ~$0.12/1M tokens
│      See: references/embedding-strategies.md
│
├─ Enterprise reliability
│  └─ OpenAI text-embedding-3-large (3072d)
│      • Industry standard
│      • ~$0.13/1M tokens
│      • Maturity shortening: reduce to 256/512/1024d
│
├─ Cost-optimized
│  └─ OpenAI text-embedding-3-small (1536d)
│      • ~$0.02/1M tokens (6x cheaper)
│      • 90-95% of large model performance
│
├─ Multilingual (100+ languages)
│  └─ Cohere embed-v3 (1024d)
│      • ~$0.10/1M tokens
│
└─ Self-hosted / Privacy-critical
   ├─ English: nomic-embed-text-v1.5 (768d, Apache 2.0)
   ├─ Multilingual: BAAI/bge-m3 (1024d, MIT)
   └─ Long docs: jina-embeddings-v2 (768d, 8K context)

核心概念

文档分块策略

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

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

为什么选择这些数值？

• 512 个 token 能平衡上下文与精确度
  • 太小（128-256）：会拆分概念，丢失上下文
  • 太大（1024-2048）：会稀释相关性，浪费大模型 token
• 50 个 token 的重叠可确保句子不会在上下文中间被拆开

如需了解按内容类型划分的高级策略，请参阅 references/chunking-patterns.md。

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

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

User Query: "OAuth refresh token implementation"
           │
    ┌──────┴──────┐
    │             │
Vector Search   Keyword Search
(Semantic)      (BM25)
    │             │
Top 20 docs   Top 20 docs
    │             │
    └──────┬──────┘
           │
   Reciprocal Rank Fusion
   (Merge + Re-rank)
           │
    Final Top 5 Results

混合搜索的重要性：

• 向量可捕捉语义含义（“OAuth refresh” ≈ “token renewal”）
• 关键词可确保精确匹配（字面匹配“refresh_token”）
• 两者结合可提供最佳检索质量

如需了解实现细节，请参阅 references/hybrid-search.md。

开始使用

Python + Qdrant 示例

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

# 1. Initialize client
client = QdrantClient("localhost", port=6333)

# 2. Create collection
client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(size=1024, distance=Distance.COSINE)
)

# 3. Insert documents with embeddings
points = [
    PointStruct(
        id=idx,
        vector=embedding,  # From OpenAI/Voyage/etc
        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. Search with metadata filtering
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' });

// Create collection
await client.createCollection('documents', {
  vectors: { size: 1024, distance: 'Cosine' }
});

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

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

完整示例请参阅 examples/typescript-rag/。

RAG 流水线架构

完整流水线组件

1. INGESTION
   ├─ Document Loading (PDF, web, code, Office)
   ├─ Text Extraction & Cleaning
   ├─ Chunking (semantic, recursive, code-aware)
   └─ Embedding Generation (batch, rate-limited)

2. INDEXING
   ├─ Vector Store Insertion (batch upsert)
   ├─ Index Configuration (HNSW, distance metric)
   └─ Keyword Index (BM25 for hybrid search)

3. RETRIEVAL (Query Time)
   ├─ Query Processing (expansion, embedding)
   ├─ Hybrid Search (vector + keyword)
   ├─ Filtering & Post-Processing (metadata, MMR)
   └─ Re-Ranking (cross-encoder, LLM-based)

4. GENERATION
   ├─ Context Construction (format chunks, citations)
   ├─ Prompt Engineering (system + context + query)
   ├─ LLM Inference (streaming, temperature tuning)
   └─ Response Post-Processing (citations, validation)

5. EVALUATION (Production Critical)
   ├─ Retrieval Metrics (precision, recall, relevancy)
   ├─ Generation Metrics (faithfulness, correctness)
   └─ System Metrics (latency, cost, satisfaction)

生产环境 RAG 的必要元数据

对筛选和相关性至关重要：

metadata = {
    # SOURCE TRACKING
    "source": "docs/api-reference.md",
    "source_type": "documentation",  # code, docs, logs, chat
    "last_updated": "2025-12-01T12:00:00Z",

    # HIERARCHICAL CONTEXT
    "section": "Authentication",
    "subsection": "OAuth 2.1",
    "heading_hierarchy": ["API Reference", "Authentication", "OAuth 2.1"],

    # CONTENT CLASSIFICATION
    "content_type": "code_example",  # prose, code, table, list
    "programming_language": "python",

    # FILTERING DIMENSIONS
    "product_version": "v2.0",
    "audience": "enterprise",  # free, pro, enterprise

    # RETRIEVAL HINTS
    "chunk_index": 3,
    "total_chunks": 12,
    "has_code": True
}

元数据的重要性：

• 可在向量搜索前进行筛选（缩小搜索范围）
• 通过定向检索提升相关性
• 支持多租户系统（按用户/组织筛选）
• 支持版本化文档（按产品版本筛选）

使用 RAGAS 进行评估

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

from ragas import evaluate
from ragas.metrics import (
    faithfulness,       # Answer grounded in context
    answer_relevancy,   # Answer addresses query
    context_recall,     # Retrieved docs cover ground truth
    context_precision   # Retrieved docs are relevant
)

# Test dataset
test_data = {
    "question": ["How do I refresh OAuth tokens?"],
    "answer": ["Use /token with refresh_token grant..."],
    "contexts": [["OAuth refresh documentation..."]],
    "ground_truth": ["POST to /token with grant_type=refresh_token"]
}

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

# Production targets:
# faithfulness: >0.90 (minimal hallucination)
# answer_relevancy: >0.85 (addresses user query)
# context_recall: >0.80 (sufficient context retrieved)
# context_precision: >0.75 (minimal noise)

性能优化

嵌入生成

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

向量搜索

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

成本优化

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

常见工作流

1. 构建 RAG 聊天机器人

• 向量数据库：Qdrant（可自托管或使用云服务）
• 嵌入：OpenAI text-embedding-3-large
• 分块：512 个 token，重叠 50 个 token，语义分割器
• 搜索：混合搜索（向量 + 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/ - 使用 Hono 的 TypeScript RAG

自动化脚本

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

---

后续步骤：

1. 根据规模和基础设施选择向量数据库
2. 根据质量与成本之间的权衡选择嵌入模型
3. 针对内容类型实施分块策略
4. 设置混合搜索，以满足生产环境的质量要求
5. 使用 RAGAS 指标进行评估
6. 针对性能和成本进行优化