Skip to content

Commit afe90f9

Browse files
SunflowersLwtechSunflowersLwtech
committed
Add Gemini embedding 2 preview specification and project embedding audit report
- Introduced `embedding-2-preview-spec.md` detailing the specifications, features, and pricing of the new Gemini embedding model. - Added `project-embedding-audit.md` for auditing the embedding usage in the SightLine project, covering both Memory and Face Recognition embedding systems. - Created `direct_intents.py` to handle direct intent logic for navigation and memory-related requests, improving the orchestration of user interactions. - Implemented `downstream_recovery.py` to manage recovery from interrupted Gemini Live downstream streams, including retry logic for transient transport errors.
1 parent deffe9c commit afe90f9

9 files changed

Lines changed: 1677 additions & 699 deletions

File tree

‎dev/docs/references/gemini-embedding-comparison/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Gemini Embedding 模型研究资料
2+
3+
> 调研日期：2026-03-13
4+
> 目的：评估 gemini-embedding-001 → gemini-embedding-2-preview 迁移可行性
5+
6+
## 文件索引
7+
8+
| 文件 | 内容 |
9+
|------|------|
10+
| `embedding-001-spec.md` | gemini-embedding-001 完整规格、benchmark、架构 |
11+
| `embedding-2-preview-spec.md` | gemini-embedding-2-preview 完整规格、新特性 |
12+
| `comparison-and-migration.md` | 1.0 vs 2.0 对比 + SightLine 迁移成本分析 |
13+
| `project-embedding-audit.md` | SightLine 代码库 embedding 使用审计报告 |
14+
15+
## 关键结论
16+
17+
- 2.0 核心突破：**多模态嵌入**（文本+图片+视频+音频+PDF）+ **4x 输入上限**
18+
- 嵌入空间**不兼容**，迁移必须全量重嵌入
19+
- 2.0 目前 **Preview**，无 Vertex AI / Batch API，**建议等 GA 再迁移**

‎dev/docs/references/gemini-embedding-comparison/comparison-and-migration.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Gemini Embedding 1.0 vs 2.0 对比 & SightLine 迁移分析
2+
3+
> 调研日期：2026-03-13
4+
5+
## 一、模型对比总表
6+
7+
| 属性 | gemini-embedding-001 (1.0) | gemini-embedding-2-preview (2.0) |
8+
|------|---------------------------|----------------------------------|
9+
| 状态 | Stable (GA) | Preview |
10+
| 发布日期 | 2025-07-14 (Stable) | 2026-03-10 (Preview) |
11+
| 输入模态 | 纯文本 | 多模态（文本+图片+视频+音频+PDF）|
12+
| 输入上限 | 2,048 tokens | 8,192 tokens (4x) |
13+
| 输出维度 | 128 ~ 3,072 (默认 3,072) | 128 ~ 3,072 (默认 3,072) |
14+
| MRL | 是 | 是 |
15+
| 语言 | 100+ | 100+ |
16+
| Task Types | 8 种 | 8 种（相同）|
17+
| Batch API | 有 (50% 折扣) | 暂无 |
18+
| Vertex AI | 有 | 暂无 |
19+
| 文本定价 | $0.15/1M tokens | $0.20/1M tokens (+33%) |
20+
| 论文 | arXiv:2503.07891 | 未发表 |
21+
| MTEB 多语言 | 68.32 (#1) | 未公布 |
22+
| MTEB 英文 | 73.30 (#1) | 未公布 |
23+
| 嵌入空间 | 空间 A | 空间 B（**不兼容**）|
24+
25+
## 二、核心区别分析
26+
27+
### 区别大不大？—— 架构差异大，API 接口几乎不变
28+
29+
#### 重大变化 (Breaking)
30+
1. **多模态嵌入** — 2.0 最大突破，文本/图片/视频/音频/PDF 映射到统一向量空间
31+
2. **4x 输入长度** — 2K → 8K tokens
32+
3. **嵌入空间不兼容** — 001 和 2-preview 向量不能混合比较
33+
34+
#### 保持不变
35+
1. API 接口 — 同样的 `embed_content()` 调用
36+
2. 维度范围 — 128 ~ 3,072，MRL 方式相同
37+
3. Task Types — 8 种完全相同
38+
4. SDK — 同一个 `google-genai` 包
39+
40+
#### 退步 / 限制
41+
1. 价格上涨 33% (文本)
42+
2. 无 Batch API（大规模操作不便）
43+
3. 无 Vertex AI（无法用 ADC 认证）
44+
4. Preview 状态，有 breaking change 风险
45+
5. 无公开 benchmark，性能不明
46+
47+
## 三、SightLine 项目迁移成本
48+
49+
### 3.1 当前 Embedding 使用概况
50+
51+
| 系统 | 模型 | 维度 | 存储 | 搜索方式 |
52+
|------|------|------|------|---------|
53+
| Memory | gemini-embedding-001 | 2048-D | Firestore Vector | find_nearest (COSINE) |
54+
| Entity Graph | gemini-embedding-001 | 2048-D | Firestore Vector | — |
55+
| Face Recognition | InsightFace ArcFace | 512-D | Firestore Vector | numpy dot product |
56+
57+
**Face 系统不受影响**（使用本地 InsightFace 模型，与 Gemini 无关）。
58+
59+
### 3.2 受影响的文件
60+
61+
#### 代码文件
62+
63+
| 文件 | 行号 | 改动内容 |
64+
|------|------|---------|
65+
| `memory/memory_bank.py` | 20-21 | EMBEDDING_MODEL 常量 + EMBEDDING_DIM |
66+
| `memory/memory_bank.py` | 34-47 | `_compute_embedding()` 函数（仅改 model 名）|
67+
| `context/entity_graph.py` | 10 | embedding 维度注释 |
68+
| `memory/memory_extractor.py` | 15 | 导入 EMBEDDING_DIM |
69+
70+
#### 基础设施
71+
72+
| 文件 | 行号 | 改动内容 |
73+
|------|------|---------|
74+
| `infrastructure/terraform/firestore.tf` | 52 | memories vector index dimension（仅维度变时）|
75+
76+
#### 测试文件
77+
78+
| 文件 | 改动内容 |
79+
|------|---------|
80+
| `tests/test_memory_bank.py` | mock 维度 `[0.1] * 2048` |
81+
| `tests/test_memory_extractor.py` | 重复检测 mock |
82+
| `tests/test_face_agent.py` | 不受影响 |
83+
| `tests/test_entity_graph.py` | entity embedding mock |
84+
85+
#### 文档/资产
86+
87+
| 文件 | 改动内容 |
88+
|------|---------|
89+
| `README.md:54,83,84` | 维度说明 |
90+
| `CLAUDE.md` | Embedding 模型 ID 和维度 |
91+
| `assets/context-memory.svg:67,138` | 架构图维度标注 |
92+
| `assets/system-architecture.svg` | 系统架构图 |
93+
94+
### 3.3 迁移场景矩阵
95+
96+
| 场景 | 代码改动 | 数据迁移 | 基础设施 | 风险 | 推荐 |
97+
|------|---------|---------|---------|------|------|
98+
| **A: 换模型 + 保持 2048-D** | 改 1 行 | 全量重嵌入 | 无需改 | 低 | -- |
99+
| **B: 换模型 + 改维度** | 改 2 行 + 测试 | 全量重嵌入 + 索引重建 | terraform apply | 中 | -- |
100+
| **C: 暂不迁移 (推荐)** | 无 | 无 | 无 | 无 | **推荐** |
101+
102+
### 3.4 数据迁移工作量
103+
104+
若选择迁移（场景 A 或 B）：
105+
106+
1. **编写迁移脚本** — 遍历 Firestore `memories` 和 `entities` 集合，对每条记录调用新模型重算 embedding
107+
2. **限流处理** — 2-preview 无 Batch API，需自行实现 rate limiting
108+
3. **索引重建** — 如果维度变化，需先删除旧 vector index，创建新 index，等待构建完成
109+
4. **验证** — 对比迁移前后的搜索质量，确保 recall 不下降
110+
5. **回滚方案** — 保留旧 embedding 字段（如 `embedding_v1`）直到验证通过
111+
112+
预估工作量：
113+
- 脚本开发: ~2h
114+
- 数据迁移执行: 取决于数据量（当前规模应 < 1h）
115+
- 验证测试: ~2h
116+
- 总计: ~半天（不含等待索引构建时间）
117+
118+
## 四、建议
119+
120+
### 短期（现在）
121+
**暂不迁移**。原因：
122+
1. 2-preview 仍是 Preview，不适合生产
123+
2. 无 Vertex AI 支持 — 我们的 Live API 走 Vertex AI (ADC)，memory/search 走 Google AI API (api_key)，但保持一致性更好
124+
3. 无 Batch API — 全量重嵌入操作不便
125+
4. 001 在 MTEB 上 #1，性能无问题
126+
5. 2-preview benchmark 未公布，性能未知
127+
128+
### 中期（2-preview GA 后）
129+
**评估迁移**，关注：
130+
1. GA 发布 + Vertex AI 支持
131+
2. Batch API 上线
132+
3. 公开 benchmark 对比
133+
4. 多模态嵌入对 SightLine 的价值（场景图片纳入 memory 语义搜索）
134+
135+
### 长期价值
136+
2.0 的**多模态嵌入**对 SightLine 有潜在重大价值：
137+
- 用户看到的场景图片可以直接嵌入 memory，不再只有文本描述
138+
- 跨模态搜索：用文字描述搜索之前看过的场景
139+
- 音频记忆：对话录音也可纳入向量检索
140+
- 这些都需要 GA + 充分测试后再考虑
141+
142+
### 维度建议
143+
无论何时迁移，**建议保持 2048-D**：
144+
- 001 的 benchmark 显示 2048-D (68.16) 与 3072-D (68.32) 几乎无差异
145+
- 节省 ~33% 存储和计算成本
146+
- 避免 Firestore vector index 重建

‎dev/docs/references/gemini-embedding-comparison/embedding-001-spec.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# gemini-embedding-001 完整规格
2+
3+
> 来源：Google AI 官方文档、arXiv:2503.07891
4+
> 调研日期：2026-03-13
5+
6+
## 1. 模型概览
7+
8+
- **Model ID**: `gemini-embedding-001`
9+
- **状态**: Stable (GA, 2025-06)
10+
- **论文**: "Gemini Embedding: Generalizable Embeddings from Gemini" (arXiv:2503.07891)
11+
- **定位**: 统一模型，合并了 text-embedding-005 (英文/代码) 和 text-multilingual-embedding-002 (多语言) 的能力
12+
13+
## 2. 技术规格
14+
15+
| 属性 | 值 |
16+
|------|-----|
17+
| 输入模态 | 纯文本 |
18+
| 最大输入 | 2,048 tokens/条 |
19+
| 单次请求上限 | 250 条文本 / 20,000 tokens |
20+
| 默认输出维度 | 3,072 |
21+
| 可选维度范围 | 128 ~ 3,072 (MRL) |
22+
| 推荐维度 | 768, 1,536, 3,072 |
23+
| 归一化 | 3,072-D 已预归一化；其他维度需手动 L2 归一化 |
24+
| 距离度量 | Cosine / Dot Product / Euclidean |
25+
| autoTruncate | 默认 true，超长静默截断 |
26+
| 语言支持 | 100+ 语言 |
27+
28+
## 3. 架构与训练
29+
30+
### 架构
31+
- 基于 Gemini LLM 初始化（具体版本/参数量未公开）
32+
- Transformer + **双向注意力**（非因果 LLM 的单向）
33+
- **Mean Pooling** → **线性投影层** → d=3,072
34+
- **Matryoshka Representation Learning (MRL)**: 推理时灵活选择维度，无需重训
35+
36+
### 两阶段训练
37+
38+
**Stage 1 — Pre-finetuning:**
39+
- 十亿级 web 语料，title-passage 正样本对
40+
- 大 batch size，长训练步数
41+
42+
**Stage 2 — Fine-tuning:**
43+
- (query, target, hard_negative) 三元组
44+
- 多任务混合数据集，每 batch 单数据集
45+
- 小 batch size (< 1,024)
46+
- 超参网格搜索
47+
48+
### 其他技术
49+
- **损失函数**: NCE (Noise Contrastive Estimation) + cosine + temperature τ
50+
- **Model Soup**: 多个 fine-tuned checkpoint 参数平均
51+
- **合成数据**: FRet/SWIM-IR 多阶段提示生成
52+
- **数据过滤**: MIRACL 平均提升 +3.9, 分类任务提升 +17.6
53+
54+
## 4. 支持的 Task Types (8 种)
55+
56+
| Task Type | 描述 |
57+
|-----------|------|
58+
| `SEMANTIC_SIMILARITY` | 文本相似度 |
59+
| `CLASSIFICATION` | 文本分类 |
60+
| `CLUSTERING` | 文本聚类 |
61+
| `RETRIEVAL_DOCUMENT` | 文档索引（支持 title 参数）|
62+
| `RETRIEVAL_QUERY` | 搜索查询（默认）|
63+
| `CODE_RETRIEVAL_QUERY` | 自然语言检索代码 |
64+
| `QUESTION_ANSWERING` | QA 文档检索 |
65+
| `FACT_VERIFICATION` | 事实核查证据检索 |
66+
67+
## 5. 性能 Benchmark
68+
69+
### MTEB 各维度分数
70+
71+
| 维度 | MTEB 分数 |
72+
|------|----------|
73+
| 3,072 | 68.32 |
74+
| 2,048 | 68.16 |
75+
| 1,536 | 68.17 |
76+
| 768 | 67.99 |
77+
| 512 | 67.55 |
78+
| 256 | 66.19 |
79+
| 128 | 63.31 |
80+
81+
### MTEB 排名
82+
83+
| 赛道 | 分数 | 排名 |
84+
|------|------|------|
85+
| 多语言 (Task Mean) | 68.32 | #1 (领先第二名 +5.09) |
86+
| 英文 v2 (Task Mean) | 73.30 | #1 |
87+
| 代码 (Mean All) | 74.66~75.5 | #1 |
88+
89+
### 多语言子项
90+
91+
| 任务 | 分数 |
92+
|------|------|
93+
| Bitext Mining | 79.32 |
94+
| Classification | 71.84 |
95+
| Clustering | 54.99 |
96+
| Pair Classification | 83.64 |
97+
| Reranking | 65.72 |
98+
| Retrieval | 67.71 |
99+
| STS | 79.40 |
100+
| Instruction Retrieval | 5.18 (弱项) |
101+
102+
### 跨语言检索
103+
104+
| 模型 | XOR-Retrieve Recall@5k |
105+
|------|----------------------|
106+
| **gemini-embedding-001** | **90.42** |
107+
| Cohere-embed-multilingual-v3.0 | 68.76 |
108+
| Gecko Embedding | 65.67 |
109+
110+
### 低资源语言 (XTREME-UP)
111+
112+
| 模型 | Avg MRR@10 |
113+
|------|-----------|
114+
| **gemini-embedding-001** | **64.33** |
115+
| voyage-3-large | 39.2 |
116+
| Gecko i18n | 35.0 |
117+
118+
### MIRACL 多语言检索
119+
- 18 语言平均: 70.1 (含数据过滤) vs 59.8 (无过滤)
120+
121+
## 6. 定价
122+
123+
| 层级 | 价格 |
124+
|------|------|
125+
| Free | $0（数据可被 Google 用于改进产品）|
126+
| Paid | $0.15 / 1M input tokens |
127+
| Paid Batch | $0.075 / 1M input tokens (50% 折扣) |
128+
129+
## 7. SDK 用法 (Python)
130+
131+
```python
132+
from google import genai
133+
from google.genai import types
134+
135+
client = genai.Client(api_key="YOUR_API_KEY")
136+
137+
# 基础嵌入
138+
result = client.models.embed_content(
139+
model="gemini-embedding-001",
140+
contents="What is the meaning of life?"
141+
)
142+
143+
# 批量 + task type + 自定义维度
144+
result = client.models.embed_content(
145+
model="gemini-embedding-001",
146+
contents=["text1", "text2", "text3"],
147+
config=types.EmbedContentConfig(
148+
task_type="SEMANTIC_SIMILARITY",
149+
output_dimensionality=768
150+
)
151+
)
152+
153+
# 手动归一化 (非 3072-D 时必须)
154+
import numpy as np
155+
vec = np.array(result.embeddings[0].values)
156+
normed = vec / np.linalg.norm(vec)
157+
```
158+
159+
SDK: `google-genai` (v1.67.0+, Python >= 3.10)
160+
161+
## 8. 已知限制
162+
163+
1. **纯文本** — 不支持图片/视频/音频/PDF
164+
2. **2,048 token 上限** — 较短
165+
3. **非 3072-D 需手动归一化**
166+
4. **与 2-preview 嵌入空间不兼容**
167+
5. **Instruction Retrieval 弱** — MTEB 仅 5.18
168+
6. **基座模型不透明** — 未公开具体 Gemini 版本和参数量
169+
170+
## 9. 关键链接
171+
172+
- 官方文档: https://ai.google.dev/gemini-api/docs/embeddings
173+
- 模型页面: https://ai.google.dev/gemini-api/docs/models/gemini-embedding-001
174+
- 论文: https://arxiv.org/abs/2503.07891
175+
- 定价: https://ai.google.dev/pricing
176+
- Vertex AI: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/embeddings/get-text-embeddings
177+
- Rate Limits: https://ai.google.dev/gemini-api/docs/rate-limits
178+
- PyPI: https://pypi.org/project/google-genai/

0 commit comments

Comments
 (0)