AI Agent Engineer

AI Agent Engineer

项目：最小向量检索器

6 min read

项目：最小向量检索器

项目目标

运行 vector_search.py，只用 Python 标准库实现 dot、L2 norm、单位化、cosine、Euclidean distance、exact top-k 和 Recall@k。test_vector_search.py用 9 项测试固定数学关系、排序方向、异常输入和命令行行为。向量是人为构造的三维教学数据，不代表真实 embedding 模型。

环境与运行

项目没有第三方依赖。为了形成稳定习惯，仍建议在 Windows 11 / PowerShell 7 中使用独立 venv，且把环境放在 vault 外：

$exampleDir = (Resolve-Path '.\Knowledge\AI Agent Engineer\docs\向量基础\examples').Path
$venv = Join-Path $env:LOCALAPPDATA 'Gao-venvs\vector-search'
$python = Join-Path $venv 'Scripts\python.exe'
 
py -3.11 -m venv $venv
& $python -m pip --version
& $python -B -W error (Join-Path $exampleDir 'vector_search.py')
& $python -B -O -W error (Join-Path $exampleDir 'vector_search.py')
& $python -B -W error -m unittest discover -s $exampleDir -p 'test_*.py' -v
& $python -B -O -W error -m unittest discover -s $exampleDir -p 'test_*.py' -v

这里不需要安装包；pip --version 只是确认后续依赖会进入正确环境。-B 禁止生成字节码缓存，-O 会移除普通 assert。脚本把关键教学检查写成显式异常，因此普通和优化模式都保留相同验收行为。

数据、输出与解释

query 是 (1, 1, 0)，三个文档向量分别代表 Python API、HTTP 重试和猫咪护理。脚本在 cosine 与 Euclidean 两种度量下都把前两个 API 文档排进 top-2：

度量第 1 名第 2 名排序方向
cosinepython-api，约 0.9986http-retry，约 0.9948越大越相似
Euclideanpython-api，约 0.1000http-retry，约 0.2449越小越相似

人工相关集合是 {python-api, http-retry}，所以 Recall@2=2/2=1.0。这只证明三条人工数据上的实现与标注一致；它不证明真实语义模型、ANN 索引或 RAG 回答质量。

读代码时回答

  1. top_k 为何让 cosine/dot 降序、Euclidean 升序？
  2. cosine 为何检查两边范数？
  3. 手工相关集合为何是评测必需，而不是从向量分数反推？
  4. 精确搜索复杂度为何随文档数与维度增长？
  5. 为什么相同分数要再按文档 ID 排序？这与可复现测试有什么关系？
  6. _require 为什么不能换成裸 assert 作为唯一运行时校验？

本轮验证

2026-07-22 复核通过

Python 3.11.9 下脚本普通模式与 -O 输出一致；9 项 unittest 在普通与 -O 的 -W error 模式下均通过。验收只使用标准库教学数据，没有凭据、网络、第三方依赖或真实 embedding 数据。

测试覆盖：已知 dot/范数/距离、单位化后 dot 与 cosine 排名一致、模长导致度量排名变化、Euclidean 升序与稳定 tie-break、Recall@k、空向量/零向量/维度不一致/NaN/Infinity、非法 k/度量/文档，以及 main() 输出。

必做扩展

  1. 给无关文档乘以 100，比较 dot 与 cosine 排名。
  2. 先单位化所有向量，验证 dot 与 cosine 排名一致。
  3. 加入两个 query 和不完整相关集，解释 Recall 的标注偏差。
  4. 用现有 Euclidean top-k 验证单位向量上的排序关系，并说明“数值不同、排序等价”的条件。
  5. 记录每条向量的假模型版本；模拟混入另一坐标空间并说明为何数学计算虽能运行、语义却无效。

常见错误与排查

错误后果排查与修正
cosine 按升序排最不相似结果被排在前面先写清“相似度越大越好、距离越小越好”
只单位化 queryinner product 不再等价于 cosinequery 与文档执行同一归一化约定
把零向量替换为很小常数后继续隐藏上游数据或模型故障明确拒绝并记录来源，修复生成链路
使用 == 比较浮点结果舍入误差导致脆弱测试用绝对/相对容差，并测试排序与边界
从检索分数生成“相关标签”评测只会重复模型偏好由任务定义和人工/权威数据建立 ground truth
exact 小数据结果直接外推 ANN忽略索引漏召回与过滤成本以 exact top-k 为基准测 ANN Recall@k、延迟和内存

掌握标准

  • 我能不依赖库实现并手算三种度量。
  • 我会为零向量和维度不一致抛出明确错误。
  • 我能根据度量方向正确排序。
  • 我能计算 Recall@k 并说明 ground truth 的局限。
  • 我不会把教学向量的结果外推成真实模型能力。
  • 我能运行普通/-O 脚本和两组测试，并解释所有异常校验为何仍然生效。

返回 向量基础目录。

参考资料

资料核验日期：2026-07-22。

Backlinks