Embedding 与向量检索

┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  One-Hot     │ → │  Word2Vec    │ → │  Transformer │ → │  现代 Embedding│
│  (离散稀疏)  │   │  (稠密低维)  │   │  (上下文感知)│   │  (多模态)    │
└──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘
    1950s              2013               2017               2023+

问题：计算机无法直接理解"语义"

没有 Embedding：文本是离散的符号序列，无法计算"相似度"
"国王"和"女王"在 One-Hot 空间中正交，余弦相似度 = 0

解决：将离散数据映射到连续向量空间

引入 Embedding：文本变成稠密向量，语义相近的文本向量距离近
"国王"和"女王"的余弦相似度 ≈ 0.85，可以用于检索和推荐

┌───────────────────────────────────────┐
│    输入文本                            │  ← "React 性能优化指南"
│    分词 → Token 序列                   │  ← ["React", "性能", "优化", "指南"]
└─────────────────┬─────────────────────┘
                  │ Tokenizer
                  ▼
┌───────────────────────────────────────┐
│    Transformer 编码器                  │  ← 多层自注意力 + FFN
│    每个 Token 生成上下文向量           │  ← [batch, seq_len, hidden_dim]
└─────────────────┬─────────────────────┘
                  │ 池化 (Pooling)
                  ▼
┌───────────────────────────────────────┐
│    输出句向量                          │  ← [1, 1536] 或 [1, 3072]
│    归一化 → 单位向量                   │  ← 用于余弦相似度计算
└───────────────────────────────────────┘

# ============================================================
# Embedding 生成过程完整实现（带详细注释）
# 比喻：Embedding 就像把一本书压缩成一段 300 字摘要——
#       分词 = 把书拆成章节
#       Transformer 编码 = 理解每段话在整本书中的含义
#       池化 = 把所有章节要点浓缩成一段摘要
#       归一化 = 统一摘要字数（方便比较）
#
# ASCII 流程图：
# ┌───────────────────────────────────────┐
# │  输入文本 "React 性能优化指南"          │
# │  → 分词 → ["React", "性能", "优化"]    │
# │  → Transformer 编码（12-24 层）        │
# │  → 池化（Mean Pooling）                │
# │  → L2 归一化                           │
# │  → 输出 [0.023, -0.156, 0.892, ...]   │
# └───────────────────────────────────────┘
# ============================================================
import numpy as np

def get_embedding(text, tokenizer, transformer_model):
    """
    生成文本的 Embedding 向量

    参数：
        text: 输入文本（如 "React 性能优化指南"）
        tokenizer: 分词器
        transformer_model: Transformer 编码器

    返回：
        embedding: 归一化后的向量 [1, dim]，用于余弦相似度计算

    关键细节：
        1. 池化策略决定向量质量——Mean Pooling 是最常用的
        2. L2 归一化使向量长度为 1，这样余弦相似度 = 点积（计算更快）
        3. 不同模型的维度不同——BGE 用 1024 维，OpenAI 用 1536 维
    """
    # --- 第 1 步：分词 ---
    # 把文本切成 Token 序列
    # "React 性能优化" → [101, 8765, 4385, 2345, 102]
    tokens = tokenizer.encode(text)

    # --- 第 2 步：Transformer 编码 ---
    # 每个 Token 通过自注意力机制"看到"所有其他 Token
    # 输出是每个 Token 的上下文相关向量
    # shape: [seq_len, hidden_dim]（如 [5, 768]）
    hidden_states = transformer_model.forward(tokens)

    # --- 第 3 步：池化（Pooling）---
    # 把变长的 Token 向量序列压缩成固定长度的句向量
    # 常见策略：
    #   Mean Pooling：取所有 Token 向量的平均值（BGE、E5 默认）
    #   CLS Token：取 [CLS] token 的输出（BERT 原生，但效果较差）
    #   Last Token：取最后一个 Token 的输出（OpenAI 默认）
    embedding = np.mean(hidden_states, axis=0)  # Mean Pooling

    # --- 第 4 步：L2 归一化 ---
    # 使向量长度为 1，这样余弦相似度 = 点积
    # 为什么重要？未归一化时，长文档的向量模长比短文档大
    # 导致检索时长文档天然得分更高（不公平！）
    norm = np.linalg.norm(embedding)
    embedding = embedding / (norm + 1e-10)  # 加 1e-10 防止除零

    return embedding  # shape: [hidden_dim]，模长 = 1

# --- 验证：两个语义相似的文本，向量距离应该很近 ---
emb1 = get_embedding("React 性能优化", tokenizer, model)
emb2 = get_embedding("避免不必要的 re-render", tokenizer, model)
emb3 = get_embedding("今天天气不错", tokenizer, model)

# 余弦相似度（归一化后 = 点积）
sim_12 = np.dot(emb1, emb2)  # 应该很高（语义相似）
sim_13 = np.dot(emb1, emb3)  # 应该很低（语义无关）
print(f"'React 性能优化' vs '避免不必要的 re-render': {sim_12:.3f}")  # ~0.85
print(f"'React 性能优化' vs '今天天气不错': {sim_13:.3f}")            # ~0.15

// Embedding 生成过程（伪代码）
async function getEmbedding(text) {
  // 1. 分词：文本 → Token 序列
  const tokens = tokenizer.encode(text);
  // "React 性能优化" → [101, 8765, 4385, 2345, 102]

  // 2. Transformer 编码：Token → 上下文向量
  const hiddenStates = transformer.forward(tokens);
  // shape: [1, seq_len, 768]

  // 3. 池化：变长向量 → 固定长度向量
  // 常见策略：Mean Pooling（取所有 token 向量的平均值）
  const embedding = meanPooling(hiddenStates, tokens);
  // shape: [1, 768]

  // 4. L2 归一化：使向量长度为 1，方便余弦相似度计算
  return l2Normalize(embedding);
  // shape: [1, 768]，向量模长 = 1
}

# ============================================================
# 向量相似度计算方法（带详细注释）
# 比喻：计算相似度就像比较两个人的"性格画像"——
#   余弦相似度：看两个人的性格方向是否一致（不管外向程度）
#   点积：同时看性格方向和外向程度
#   欧氏距离：看两个人的性格画像"差多远"
# ============================================================
import numpy as np

def cosine_similarity(a, b):
    """
    余弦相似度：衡量两个向量的方向相似性

    值域：[-1, 1]
      1 = 完全相同方向
      0 = 正交（无关）
     -1 = 完全相反方向

    比喻：两个人的兴趣方向是否一致——
          都喜欢编程和音乐 → 高相似度
          一个喜欢编程一个喜欢烹饪 → 低相似度
          （不管他们各自的兴趣有多强烈）

    适用场景：文本语义检索（最常用）
    """
    dot_product = np.dot(a, b)          # 点积：方向一致程度
    norm_a = np.linalg.norm(a)           # 向量 a 的模长
    norm_b = np.linalg.norm(b)           # 向量 b 的模长
    return dot_product / (norm_a * norm_b + 1e-10)  # 防止除零

def dot_product(a, b):
    """
    点积：同时受方向和模长影响

    值域：(-inf, +inf)

    适用场景：
      1. 向量已归一化时（此时点积 = 余弦相似度，计算更快）
      2. 推荐系统中需要考虑热度（模长代表热度）
    """
    return np.dot(a, b)

def euclidean_distance(a, b):
    """
    欧氏距离：两个向量在空间中的"直线距离"

    值域：[0, +inf)
      0 = 完全相同
      越大 = 差异越大

    适用场景：聚类算法（K-Means）、异常检测
    """
    return np.linalg.norm(a - b)

# --- 关键细节 ---
# 1. 如果向量已 L2 归一化，余弦相似度 = 点积（计算更快）
# 2. 向量数据库通常同时支持这三种距离度量
# 3. 文本检索默认用余弦相似度，推荐系统用点积，聚类用欧氏距离

# --- 验证 ---
a = np.array([0.023, -0.156, 0.892])  # "React 性能优化" 的向量
b = np.array([0.025, -0.153, 0.889])  # "避免不必要的 re-render" 的向量
c = np.array([0.782, 0.341, -0.125])  # "今天天气不错" 的向量

print(f"余弦相似度 (a,b): {cosine_similarity(a, b):.3f}")  # ~0.999（很相似）
print(f"余弦相似度 (a,c): {cosine_similarity(a, c):.3f}")  # ~-0.3（不相似）

// 1. 余弦相似度（Cosine Similarity）—— 最常用
// 衡量两个向量的方向相似性，值域 [-1, 1]
function cosineSimilarity(a, b) {
  let dotProduct = 0,
    normA = 0,
    normB = 0;
  for (let i = 0; i < a.length; i++) {
    dotProduct += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
}

// 如果向量已经 L2 归一化，余弦相似度 = 点积
// cos(a, b) = a · b / (|a| × |b|) = a · b（当 |a|=|b|=1）
function cosineSimilarityNormalized(a, b) {
  return a.reduce((sum, ai, i) => sum + ai * b[i], 0);
}

// 2. 点积（Dot Product）—— 用于归一化向量或需要考虑向量模长的场景
function dotProduct(a, b) {
  return a.reduce((sum, ai, i) => sum + ai * b[i], 0);
}

// 3. 欧氏距离（L2 Distance）—— 向量数据库常用
function euclideanDistance(a, b) {
  return Math.sqrt(a.reduce((sum, ai, i) => sum + (ai - b[i]) ** 2, 0));
}

// OpenAI text-embedding-3 支持动态维度（Matryoshka Representation Learning）
// 可以在请求时指定 dimensions 参数，无需重新训练
const embedding1536 = await openai.embeddings.create({
  model: "text-embedding-3-small",
  input: "React 性能优化",
  dimensions: 1536, // 默认维度，最高精度
});

const embedding512 = await openai.embeddings.create({
  model: "text-embedding-3-small",
  input: "React 性能优化",
  dimensions: 512, // 截断维度，节省约 67% 存储，精度小幅下降
});

┌─────────────────────────────────────────────────────┐
│                    RAG 系统架构                       │
├─────────────────────────────────────────────────────┤
│                                                     │
│  用户查询 ──→ Embedding 模型 ──→ 查询向量            │
│                                        │            │
│                                        ▼            │
│                              ┌──────────────┐       │
│                              │  向量数据库    │       │
│                              │  (Top-K 检索)  │       │
│                              └──────┬───────┘       │
│                                     │               │
│  离线阶段：                          ▼               │
│  文档 ──→ 切片 ──→ Embedding ──→ 文档向量入库        │
│                                                     │
│  相关文档 + 用户查询 ──→ LLM ──→ 最终回答            │
└─────────────────────────────────────────────────────┘

你的业务需要多语言支持吗？
├── 是 → BGE-M3（开源免费、100+ 语言、支持稠密/稀疏/多向量融合检索）
│        或 Cohere Embed v3（托管服务、100+ 语言、内置压缩）
└── 否 → 主要处理中文？
         ├── 是 → BGE-M3 或 GTE-large（中文优化最好）
         └── 否 → 主要处理英文？
                  ├── 预算有限 → text-embedding-3-small（$0.02/1M tokens）
                  ├── 需要最高精度 → text-embedding-3-large（维度更高、精度更强）
                  └── 自建部署 → E5-large-v2 或 all-MiniLM-L6-v2

// 实际调用示例：OpenAI Embedding
import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.embeddings.create({
  model: "text-embedding-3-small",
  input: "如何优化 React 组件的渲染性能",
  dimensions: 1024, // 使用 Matryoshka 截断到 1024 维
});

console.log(response.data[0].embedding); // [0.0123, -0.0456, ...]
console.log(response.data[0].embedding.length); // 1024
console.log(response.usage.total_tokens); // 消耗的 token 数

# 实际调用示例：BGE-M3（HuggingFace Transformers）
from FlagEmbedding import BGEM3FlagModel

model = BGEM3FlagModel('BAAI/bge-m3', use_fp16=True)

# 稠密检索
dense_embeddings = model.encode(
    ["如何优化 React 组件的渲染性能"],
    batch_size=12,
    max_length=8192,
)['dense_vecs']

# 融合检索（稠密 + 稀疏 + 多向量）
output = model.encode(
    ["如何优化 React 组件的渲染性能"],
    return_dense=True,
    return_sparse=True,
    return_colbert_vecs=True,
)

// Sentence Transformers 微调示例（Python 伪代码）
// 使用对比学习微调 Embedding 模型
const trainingConfig = {
  model: "BAAI/bge-base-en-v1.5", // 基座模型
  loss: "MultipleNegativesRankingLoss", // 损失函数
  epochs: 3,
  batchSize: 64,
  learningRate: 2e-5,

  // 训练数据格式：正样本对
  // { "anchor": "如何优化 React 性能?", "positive": "避免不必要的 re-render" }
  // 模型学习让 anchor 和 positive 的向量距离更近
};

你的数据规模有多大？
├── < 100 万向量 → Chroma（轻量、开发友好）或 PGVector（已有 PostgreSQL）
├── 100 万 ~ 1 亿 → Qdrant（Rust 高性能）或 Weaviate（混合检索）
└── > 1 亿 → Milvus（分布式架构）或 Pinecone（全托管免运维）

你需要混合检索吗？（向量 + 关键词）
├── 是 → Weaviate（原生支持 BM25 + 向量融合）或 Milvus 2.4+（支持）
└── 否 → 任何数据库都可以

你的团队有运维能力吗？
├── 有 → Milvus / Qdrant / Weaviate（开源自建，成本低）
└── 没有 → Pinecone（全托管，零运维）或 Zilliz Cloud（Milvus 托管版）

// 向量数据库使用示例：Milvus
import { MilvusClient } from "@zilliz/milvus2-sdk-node";

const client = new MilvusClient({ address: "localhost:19530" });

// 1. 创建集合（表）
await client.createCollection({
  collection_name: "documents",
  fields: [
    { name: "id", data_type: "Int64", is_primary_key: true },
    { name: "text", data_type: "VarChar", max_length: 2000 },
    { name: "embedding", data_type: "FloatVector", dim: 1536 },
  ],
});

// 2. 创建 HNSW 索引（加速检索）
await client.createIndex({
  collection_name: "documents",
  field_name: "embedding",
  index_type: "HNSW",
  metric_type: "COSINE",
  params: { M: 16, efConstruction: 200 },
});

// 3. 插入向量
await client.insert({
  collection_name: "documents",
  data: [
    { id: 1, text: "React 性能优化", embedding: [...1536维向量] },
    { id: 2, text: "Vue 响应式原理", embedding: [...1536维向量] },
  ],
});

// 4. 向量检索
const results = await client.search({
  collection_name: "documents",
  vectors: [queryEmbedding], // 查询向量
  limit: 10,                 // Top-K
  output_fields: ["text"],
  metric_type: "COSINE",
});

// 向量数据库使用示例：PGVector（PostgreSQL 扩展）
// 适合已有 PostgreSQL 的团队，无需引入新基础设施
import pg from "pg";
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

// 1. 创建表（启用 pgvector 扩展）
await pool.query(`
  CREATE EXTENSION IF NOT EXISTS vector;
  CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    text TEXT,
    embedding vector(1536)
  );
`);

// 2. 创建 HNSW 索引
await pool.query(`
  CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 200);
`);

// 3. 向量检索（余弦相似度）
const results = await pool.query(
  `
  SELECT text, 1 - (embedding <=> $1::vector) AS similarity
  FROM documents
  ORDER BY embedding <=> $1::vector
  LIMIT 10
`,
  [JSON.stringify(queryEmbedding)],
);

// 训练数据格式：正样本对
// 目标：让语义相似的文本对向量距离更近，不相似的更远
const trainingData = [
  {
    anchor: "如何优化 React 组件的渲染性能?",
    positive: "避免不必要的 re-render 和使用 React.memo", // 正样本
  },
  {
    anchor: "什么是闭包?",
    positive: "闭包是函数与其词法环境的组合", // 正样本
  },
  // 负样本由其他 batch 内的样本自动构成（In-batch Negatives）
];

// 损失函数：MultipleNegativesRankingLoss (MNR)
// 对于每个 anchor，batch 内其他所有样本都是负样本
// 如果 batch_size=64，每个 anchor 有 1 个正样本 + 62 个负样本

// 显式指定正样本和负样本
const tripletData = [
  {
    anchor: "React 性能优化",
    positive: "使用 React.memo 避免 re-render",
    negative: "Vue 的响应式原理", // 语义相关但不是正样本
  },
];

// 损失函数：TripletLoss
// 目标：distance(anchor, positive) + margin < distance(anchor, negative)
// margin 通常设为 0.2-0.5

// 用大模型（如 GPT-4）作为教师模型，生成查询-文档的相关性评分
// 用小模型学习模仿大模型的排序能力
const distillationData = [
  {
    query: "React 性能优化方法",
    // GPT-4 给出的排序（教师信号）
    passages: [
      { text: "使用 React.memo 和 useMemo", score: 0.95 },
      { text: "代码分割和懒加载", score: 0.8 },
      { text: "Vue 的 Composition API", score: 0.1 },
    ],
  },
];
// 小模型学习：让 0.95 分的文档向量更接近查询，0.10 分的更远

// 难负例挖掘（Hard Negative Mining）
// 用 BM25 或通用 Embedding 检索，取出"相似但不相关"的文档作为负例
async function mineHardNegatives(query, corpus, embeddingModel, topK = 100) {
  // 1. 用通用 Embedding 检索 top-100
  const candidates = await search(query, corpus, { topK: 100 });

  // 2. 过滤掉已标注为正样本的文档
  const hardNegatives = candidates.filter((doc) => !isPositive(query, doc));

  // 3. 取 top-10 作为难负例（与查询语义相近但不相关）
  return hardNegatives.slice(0, 10);
}

// MRL 训练的核心思想
// 同时计算 256、512、1024、3072 维的损失，加权求和
// 训练完成后，可以根据需要截断到任意维度

// 伪代码
function mrlLoss(embedding, positiveEmbedding, dimensions = [256, 512, 1024]) {
  let totalLoss = 0;
  for (const dim of dimensions) {
    const truncatedEmb = embedding.slice(0, dim);
    const truncatedPos = positiveEmbedding.slice(0, dim);
    totalLoss += contrastiveLoss(truncatedEmb, truncatedPos);
  }
  return totalLoss / dimensions.length;
}

┌──────────────────────────────────────────────────────┐
│  输入文本（12000 tokens）                              │
│  ├─ 前 8191 tokens ──→ 被编码为向量（包含语义）        │
│  └─ 后 3809 tokens ──→ 被静默截断（语义丢失）          │
│                                                      │
│  如果文档的关键结论在最后 3000 tokens，检索时永远找不到  │
└──────────────────────────────────────────────────────┘

# ❌ 错误：一次性写入大量文档，部分向量可能变成零向量
vectorstore.add_documents(all_documents)  # 如果 all_documents 超过 10000 条

# ✅ 正确：分批写入，每批 200 条
from itertools import islice

def batch_iterable(iterable, batch_size):
    it = iter(iterable)
    while True:
        batch = list(islice(it, batch_size))
        if not batch:
            break
        yield batch

for batch in batch_iterable(all_documents, 200):
    vectorstore.add_documents(batch)

// 创建 kNN 索引时指定参数
// PUT /my-index
{
  "mappings": {
    "properties": {
      "embedding": {
        "type": "dense_vector",
        "dims": 1536,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "hnsw",
          "m": 32,
          "ef_construction": 200
        }
      }
    }
  }
}

// 前端处理推理模型的流式响应
const response = await fetch("/api/chat", {
  method: "POST",
  body: JSON.stringify({ model: "deepseek-reasoner", message: userInput }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let answer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = JSON.parse(decoder.decode(value));

  if (chunk.choices[0].delta.reasoning_content) {
    // reasoning_content：模型思维链，前端可选择折叠展示或直接隐藏
    showThinking(chunk.choices[0].delta.reasoning_content);
  }

  if (chunk.choices[0].delta.content) {
    // content：最终答案，正常渲染
    answer += chunk.choices[0].delta.content;
    renderAnswer(answer);
  }
}

# Transformer 自注意力（简化伪代码）
# 输入：token_embeddings [batch, seq_len, hidden_dim]

# 1. 线性投影生成 Q, K, V
Q = token_embeddings @ W_q  # [batch, seq_len, hidden_dim]
K = token_embeddings @ W_k
V = token_embeddings @ W_v

# 2. 计算注意力分数
scores = Q @ K.transpose(-2, -1) / sqrt(hidden_dim)
# [batch, seq_len, seq_len] — 每个 token 对其他 token 的注意力

# 3. Softmax 归一化
attention_weights = softmax(scores, dim=-1)

# 4. 加权求和
output = attention_weights @ V
# [batch, seq_len, hidden_dim] — 上下文相关的向量表示

# 5. 多头：将 hidden_dim 拆成 num_heads 个子空间，独立计算注意力
# 捕捉不同维度的语义关系（语法、语义、指代等）

# Mean Pooling：对所有有效 Token 的向量取平均
# attention_mask 区分真实 Token 和 Padding Token
def mean_pooling(model_output, attention_mask):
    token_embeddings = model_output.last_hidden_state  # [batch, seq_len, hidden]
    input_mask = attention_mask.unsqueeze(-1)           # [batch, seq_len, 1]
    # 只对真实 Token 求和，忽略 Padding
    sum_embeddings = torch.sum(token_embeddings * input_mask, dim=1)
    sum_mask = torch.clamp(input_mask.sum(dim=1), min=1e-9)
    return sum_embeddings / sum_mask  # [batch, hidden]