Embedding
知识库简介
Embedding（嵌入）把文本、图片或其他对象映射为固定长度的数值向量，让模型训练目标下“关系相近”的对象在向量空间中更容易被找到。对 AI Agent Engineer 而言，关键不是拿到一串浮点数，而是维护一份完整空间契约：
- 用什么模型、revision 与输入角色编码；
- 输出多少维、是否归一化、使用什么距离；
- 输入是否被截断，向量对应哪一版正文；
- 批处理如何对账、重试、缓存与计费；
- 新旧空间如何隔离、评测、切换和回滚。
向量相近只是一种候选召回信号，不代表事实正确、来源可信、用户有权限或答案完整。可靠 RAG 仍需 metadata 过滤、关键词/混合检索、rerank、引用和端到端评测。
动态事实边界
模型名称、输入限制、维度选项、角色参数、归一化行为、价格与 SDK API 会变化。本库只记录截至 2026-07-22 核对过的原则和示例；实施时必须回到所选模型的当前官方文档或模型卡。
在总路线中的位置
向量基础提供点积、范数与余弦直觉；Chunking策略定义要编码的证据文本；本库把 query 与 documents 转为可比较表示。后续 向量数据库、语义搜索、Reranking 和 RAG将这些表示用于检索和回答。
学习目标
完成本库后，你应能：
- 从 one-hot、静态词向量理解到上下文与句子/文档 embedding；
- 解释“相似”为什么依赖训练数据、目标、输入角色和度量；
- 按语言、领域、任务、许可、隐私、限制、延迟、成本与业务 gold set 选择模型；
- 区分 query/document 编码、对称/非对称检索和 bi-encoder/reranker；
- 正确使用 cosine、dot product、Euclidean distance 与 L2 归一化；
- 构建可对账的批处理、缓存键、失败分类与质量校验；
- 阻止零向量、NaN/Inf、维度错误、静默截断和跨空间混查；
- 用 Recall@k、MRR、nDCG、子组、延迟与成本评测候选；
- 通过双索引重建、影子评测、原子切换和回滚迁移模型。
前置知识
- 向量基础：向量、点积、范数和余弦；
- API：超时、限流、重试与错误分类；
- Chunking策略：输入边界、来源哈希和 ACL；
- Python 函数、dataclass、JSON 与 PowerShell 基础。
不会机器学习训练也可以开始；本库聚焦“使用和评测 embedding”，训练细节只解释到理解空间含义所需程度。
核心术语
| 术语 | 初学者解释 | 工程约束 |
|---|---|---|
| embedding vector | 模型为一个输入产生的定长浮点数组 | 必须绑定模型、revision、角色、维度与预处理 |
| embedding space | 同一编码契约产生、可用指定度量比较的坐标空间 | 维度相同不等于空间兼容 |
| bi-encoder | query 与 document 分别编码，再快速比较向量 | 适合大规模候选召回 |
| query/document role | 模型为查询和语料定义的不同任务指令或编码路径 | 按官方模型契约调用 |
| metric | cosine、dot 或距离等排序规则 | 与训练/归一化/索引配置一致 |
| normalization | 将向量除以 L2 norm 变成单位向量 | 不是对所有模型都应盲目执行 |
| exact search | 与所有候选逐一算分 | 小规模 gold 与 ANN ground truth |
| ANN | 近似最近邻 | 用少量召回损失换速度/内存 |
| space migration | 从旧模型/契约重建到新空间 | 双索引隔离，不能混写混查 |
推荐学习顺序
| 顺序 | 课程 | 产出 |
|---|---|---|
| 1 | 表示学习与向量直觉 | 能解释向量“相近”的来源与边界 |
| 2 | 模型、维度与归一化选择 | 一张可审计的模型候选卡与对照实验 |
| 3 | 批处理、缓存与可靠性 | 可恢复、可对账、不泄露正文的编码流水线 |
| 4 | 相似度、索引与版本迁移 | 空间契约、双索引迁移与回滚门禁 |
| 5 | 评测与迁移项目 | 两套隔离空间的 exact 检索、指标与迁移审计 |
建议按顺序完成。模型选择前先理解表示含义；接入 API 前先定义空间契约；迁移前先固定业务查询与机械对账门禁。
动手实践入口
- evaluate_embedding_space.py：严格加载、向量校验、exact search、ACL、Recall/MRR/nDCG、子组和迁移审计；
- embedding-fixture.json：两个维度/metric 不同且隔离的手工教学空间；
- test_evaluate_embedding_space.py：32 项输入、数学、授权、评测、迁移与 CLI 测试；指标入口拒绝重复 ranked ID、非法 relevance grade 与会在 float 转换时溢出的 fixture 数值。
从项目根目录（同时包含 docs/ 与 .website/）运行：
$env:PYTHONDONTWRITEBYTECODE = '1' # 禁止生成 __pycache__，避免运行实验污染知识库目录。
python -B -W error '.\docs\Embedding\examples\evaluate_embedding_space.py' # 执行两套离线向量空间的检索与迁移审计。
python -B -W error -m unittest discover -s '.\docs\Embedding\examples' -p 'test_evaluate_embedding_space.py' -v # 发现并详细运行 Embedding 示例的单元测试。项目完全离线，不下载模型、不需要 API key。手工向量只能验证合同与指标代码，不能证明任何真实模型质量。
掌握标准
- 我能区分 one-hot、静态 token、上下文 token、句子/文档和多模态 embedding。
- 我能解释 bi-encoder 召回与 cross-encoder rerank 的职责差异。
- 模型记录含 provider/model/revision、角色/指令、维度、dtype、metric、归一化与输入限制。
- 我只在模型明确支持时使用可变维度或向量压缩，并在业务集上重新评测。
- 批处理逐项对账，拒绝空/零/非有限/错维向量和静默截断。
- 缓存键包含完整空间契约与输入哈希，向量继承原文安全级别。
- query 与 documents 始终来自兼容空间，ACL 在评分前生效。
- 新旧空间物理或逻辑隔离，query 分别编码后独立检索。
- 我会报告 per-query、子组、Recall/MRR/nDCG、延迟、吞吐、存储和费用。
- 公开榜单只用于筛选，最终决策来自目标语料与查询。
与其他知识库的关系
| 知识库 | 关系 |
|---|---|
| 向量基础 | 解释点积、范数、距离和高维几何 |
| Chunking策略 | 决定 document embedding 的输入和哈希 |
| LLM API集成 | 提供客户端超时、重试、限流和可观测性模式 |
| 向量数据库 | 存储向量、metadata、过滤字段和 ANN 索引 |
| 语义搜索 | 组合 query 编码、过滤、召回与混合检索 |
| Reranking | 对 bi-encoder 候选做更细 query-document 交互 |
| 评测体系 | 管理数据划分、统计不确定性和发布门禁 |
| RAG | 测试引用支持、答案正确与无答案拒答 |
主要参考资料
- Google Machine Learning Crash Course: Embeddings
- Mikolov et al., Efficient Estimation of Word Representations in Vector Space
- Reimers & Gurevych, Sentence-BERT
- Sentence Transformers Usage
- MTEB Overview
- MTEB original paper
- OpenAI: Vector embeddings
- Gemini API: Embeddings
- Cohere: Introduction to Embeddings
来源获取/复核日期：2026-07-22。提供商文档是动态事实，具体 API/限制须在实现当天重新核对。