Embeddings、切分与相似度

1. 解决什么问题

教材资料可能没有与需求完全相同的字面表达。Embedding 把文本表示为数值向量，允许通过距离找出语义相关候选。切分则把长资料变成可检索、可引用、能放入上下文的小片段。

2. 原理与术语

向量维度是每条表示包含的数值数量；余弦距离比较方向差异。相似度不是事实可信度，也不是模型自信概率。真实模型的语义表示来自训练；确定性哈希只提供可复现数值，不能宣称具有同等语义能力。

3. 输入、输出和执行

split_text 输入整段文本，输出起止偏移与片段；默认每片 320 个 Python 字符、重叠 50 字符。embeddings 输入片段列表，返回等长向量列表。资料和查询必须使用可比较的模型、维度与预处理方式。

4. 容易混淆

字符切分不等于 token 切分，也不是按语义段落切分。重叠减少边界信息丢失，却增加向量和提示词成本。阿语字符、标点与中文在 tokenizer 中的长度不同，不能把 320 字符当成固定 token 预算。

5. 最小示例

from app.retrieval import split_text
parts = list(split_text("ABCDEFGHIJ", size=6, overlap=2))
assert parts == [(0, 6, "ABCDEF"), (4, 10, "EFGHIJ")]
print(parts)

偏移采用左闭右开区间。保存偏移比只存片段文本更利于回到原文核对。

6. 实际实现

演示模式将相邻二字符哈希到 64 维并归一化，namespace 明确标记 demo:sha256-bigram:v1:64。真实模式调用 /embeddings，配置维度，检查返回数量、维度和有限数值；失败会报错，不会改用演示向量补齐。

7. 源码与数据结构

关键代码为 system/app/retrieval.py::split_text/embeddings/import_document，namespace 在 settings.py::Settings.namespace。chunks 保存 document_id、ordinal、start_offset、end_offset、text 与 embedding；导入先生成全部向量，再开启数据库事务。

8. 设计取舍

字符窗口便于理解和复现，但可能把题目与答案切开。改成段落或标题优先切分后，需比较召回和来源定位，不只比较片段数。更换真实模型时应建立新 namespace 并重新导入，不能把同维度当成同一向量空间。

9. 实验与验收

在 system 目录的演示模式运行：

docker compose exec -T api python - <<'PY'
from app.retrieval import embeddings, split_text
parts=list(split_text('校园学习。'*100))
v=embeddings(['校园学习','校园学习'])
assert len(v[0])==64 and v[0]==v[1]
print('chunks=',len(parts),'dimension=',len(v[0]))
PY

该实验只验证切分、维度和确定性。真实语义验收必须使用真实配置，对人工标注的同义和无关文本比较召回；不能把两个相同字符串的向量相等当成语义理解证据。

10. 故障排查

维度错误先查 EMBEDDING_DIMENSIONS 与服务能力；数量错误查批量响应 index；空查询或极短文本注意边界。命中质量低时依次检查切分、资料适用范围、模型和 query，不要先把所有责任归给 pgvector。

11. 面试题与追问

问：Embedding 和向量数据库谁负责理解文本？ 模型产生表示，数据库按度量检索。追问：换模型只改配置可以吗？ 不够，要隔离旧向量并重新导入。再追问：重叠越大越好吗？ 不一定，会增加重复候选和成本，应通过固定查询集衡量。

STAR 应用：假设实验场景，R 为应核对的证据

对应	S：情境	T：目标	A：行动	R：验收证据
主问	同义查询没有命中资料	定位表示与检索责任	分别检查切分、向量模型和数据库范围	能指出是哪一层遗漏，不能只换数据库
追问一	切换向量模型	避免不同空间混用	新namespace并重新导入	查询只比较对应模型及维度的向量
追问二	加大重叠窗口	评估边界收益和成本	固定查询集比较召回与片段数	同时记录重复候选和调用开销

这些是设计讨论的参考表达，实际执行前不能改写为已取得的历史成果。

12. 官方资料与版本

OpenAI Embeddings、pgvector。核验日期 2026-11-03；项目真实模型名与维度来自配置，演示维度固定 64。对比扩展见Embedding 与 Reranker。