Retrieval Augmented Generation（RAG）架构是当前企业 AI 应用的主流选择，但当业务增长到一定规模，或者需要切换底层技术栈时，RAG 迁移就成了每个 AI 工程师都必须面对的棘手问题。向量数据库的选型、Embedding 模型的更换、分块策略的调整、检索逻辑的重构——每一个环节都可能引入意想不到的坑。
Gemini CLI 是 Google 推出的 AI 编程 Agent CLI 工具，通过自然语言对话即可驱动代码生成、文件修改、终端命令执行和复杂任务拆解。本文以一个真实场景为例，完整演示如何用 Gemini CLI 完成从 ChromaDB 到 Pinecone 的 RAG 系统迁移，并顺便完成 Embedding 模型从 OpenAI Ada-002 到本地 Claude Embeddings 的切换。
一、为什么 RAG 迁移比想象中更复杂很多人以为 RAG 迁移就是「换个数据库连接」那么简单。实际上，RAG 系统由多个高度耦合的组件构成，迁移任何一个环节都可能产生连锁反应。
1. 向量数据库的差异不是 API 兼容的ChromaDB 支持的元数据过滤、相似度度量、索引类型在 Pinecone 中可能有不同的参数名称和行为。即便是「简单」的 upsert 操作，两者的批量大小限制和分片策略也不尽相同。
2. Embedding 模型决定语义空间切换 Embedding 模型意味着所有已有向量在语义空间中不再等价。你不能简单地把旧向量 Re-embedding 后塞进新数据库就了事——你需要在某个时间点接受新旧数据的不一致窗口期。
3. 分块策略影响检索粒度不同的分块大小（chunk_size）会直接影响检索命中率。如果原来用 512 tokens 的分块，切换到 1024 tokens 后，很多长文本中的细粒度信息可能无法被准确召回。
4. 检索逻辑需要同步调整重排序（rerank）策略、混合检索（关键词 + 向量）的权重配置、Top-K 数量——这些参数往往和向量数据库、Embedding 模型紧密耦合，迁移时需要全套重新调优。
二、迁移方案设计：三步走在动手之前，我先用 Gemini CLI 做一次完整的迁移方案设计。这个阶段的核心目标是理清迁移范围、评估风险、制定回滚策略。
Step 1：用 Gemini CLI 分析现有代码库把整个 RAG 项目的目录结构告诉 Gemini CLI，让它生成一份组件关系图和迁移影响分析。
# 在项目根目录启动 Gemini CLI
npx @google/gemini-cli
# 输入以下指令
请分析当前项目的 RAG 实现：
1. 列出所有与向量存储相关的文件和函数
2. 标注哪些地方直接依赖 ChromaDB 客户端
3. 识别 Embedding 模型调用链路
4. 给出迁移到 Pinecone + Claude Embeddings 的影响范围报告Gemini CLI 会遍历项目文件，输出一个清晰的依赖分析。它能识别出类似这样的高风险耦合点：
rag/retriever.py直接实例化chromadb.Clientrag/embedding.py调用 OpenAI Embedding APIrag/chunker.py硬编码 chunk_size=512
迁移过程中最怕的就是数据断层。推荐的做法是引入一个抽象层，实现双写——新旧系统同时写入，读取端逐步切换。
请设计一个向量存储抽象层 VectorStoreInterface，要求：
1. 支持 ChromaDB 和 Pinecone 两种后端，通过配置切换
2. 实现双写模式：新旧数据库同时写入
3. 提供 read_switch 方法，支持按比例（如 5%/95%）切换读取源
4. 确保接口幂等，双写过程不产生重复数据
给出完整的 Python 抽象类和两种后端的实现代码。Gemini CLI 会生成类似这样的抽象层结构：
class VectorStoreInterface:
def upsert(self, chunks: list[Chunk], dual_write: bool = False) -> None
def query(self, text: str, top_k: int, read_ratio: float = 1.0) -> list[Chunk]
def migrate_batch(self, batch_size: int = 1000) -> MigrationReport
class PineconeStore(VectorStoreInterface):
# Pinecone 特定实现
...
class ChromaStore(VectorStoreInterface):
# ChromaDB 特定实现
...双写稳定后，下一步是逐步将读取流量从 ChromaDB 切换到 Pinecone。关键是这个过程必须可观测、可回滚。
三、Gemini CLI 驱动迁移：完整实录以下是实际使用 Gemini CLI 进行迁移的核心步骤和指令实录。为方便阅读，我做了适当的精简和重组。
3.1 生成迁移脚本骨架$ npx @google/gemini-cli
> 请生成一个完整的数据迁移脚本 migrate_to_pinecone.py，要求：
>
> 输入：
> - ChromaDB 集合名称（默认 'documents'）
> - Pinecone 索引名称（默认 'documents-v2'）
> - 批处理大小（默认 500）
>
> 处理逻辑：
> 1. 连接 ChromaDB 读取所有文档和向量
> 2. 对每条记录重新计算 Embedding（使用 Claude）
> 3. 写入 Pinecone（带原 metadata）
> 4. 打印进度和迁移报告
>
> 异常处理：
> - 单条失败不影响整批
> - 失败记录保存到 failed_migrations.json
> - 完成后输出统计：成功/失败/跳过数量Gemini CLI 会根据项目中的现有代码风格生成符合规范的脚本。
3.2 修复 Embedding 维度不匹配问题迁移过程中最容易遇到的坑是维度不匹配。OpenAI Ada-002 输出 1536 维向量，而 Claude Embeddings 默认输出 1024 维。如果直接把旧数据用新模型重新计算并写入，Pinecone 索引的 dimension 设置必须同步调整。
$ npx @google/gemini-cli
> 我的 Pinecone 索引 dimension 应该是多少？
> 旧系统用 OpenAI Ada-002（1536维），新系统要用 Claude Embeddings。
> 另外帮我检查一下 Pinecone 初始化代码有没有其他参数需要同步修改。Gemini CLI 查看了我的 Pinecone 初始化代码后，指出需要同步修改的地方：
dimension从 1536 改为 1024metric确认使用cosine（Claude Embeddings 推荐）- 添加
pod_type建议（p1.x1或s1.x1根据规模选择）
ChromaDB 和 Pinecone 的元数据格式不同。ChromaDB 支持列表型元数据（如 tags: ["AI", "RAG"]），而 Pinecone 的元数据字段有 40KB 限制，且不支持列表——需要展平为字符串数组或 JSON 字符串。
$ npx @google/gemini-cli
> 帮我写一个元数据转换函数 metadata_transform(metadata: dict) -> dict，
> 要求：
> 1. 将列表类型字段展平为逗号分隔字符串
> 2. 将过长的字符串截断至 1000 字符
> 3. 过滤掉 None 值字段
> 4. 保留原始字段名和转换记录（用于调试）原有检索逻辑重度依赖 ChromaDB 的 where 过滤语法，切换到 Pinecone 后需要改用 Pinecone 的元数据过滤表达式。这是一个容易出错的重构点。
$ npx @google/gemini-cli
> 请将以下 ChromaDB 检索代码迁移到 Pinecone：
>
> 原有代码：
> results = collection.query(
> query_texts=[query],
> n_results=top_k,
> where={"source": source_filter, "year": {"$gte": 2023}},
> include=["documents", "metadatas", "distances"]
> )
>
> 我需要知道 Pinecone 的等效写法，以及新旧两种写法的语义差异说明。Gemini CLI 给出了 Pinecone 的等效写法，并特别标注了容易忽略的差异点：
# Pinecone 等效写法
from pinecone import Pinecone, ServerlessSpec
pc = Pinecone()
index = pc.Index("documents-v2")
results = index.query(
vector=embeddings, # 需要先计算 query 的 embedding
top_k=top_k,
filter={
"source": {"$eq": source_filter},
"year": {"$gte": 2023}
},
include_metadata=True
)
# 关键差异：
# 1. Pinecone 需要预计算 query 向量，无法直接传文本
# 2. 距离计算方式不同：ChromaDB 用 L2/P cosine，Pinecone 用余弦相似度
# 3. $lte / $gte 在 Pinecone 中写法一致，但数据类型必须匹配（字符串 vs 数字）代码迁移完成后，数据也写入了新数据库，但这并不意味着迁移成功。你还需要做一套完整的验证流程。
4.1 数据一致性验证$ npx @google/gemini-cli
> 请写一个验证脚本 verify_migration.py，实现以下功能：
>
> 1. 从 ChromaDB 和 Pinecone 分别用相同的 query 检索结果
> 2. 计算两者的语义相似度（用 Claude 评估两批结果的相关性）
> 3. 设定阈值：相似度 < 0.85 的 query 标记为高风险
> 4. 输出 CSV 报告：高风险 query、差异描述、建议操作
>
> 测试用例需覆盖：
> - 短文本查询（< 50字）
> - 长文本查询（> 500字）
> - 多条件过滤查询
> - 空结果查询除了逐条对比，你还需要一个宏观的召回率指标。准备一个黄金测试集（golden query set），包含 100-200 个典型 query 和对应的期望文档，然后用迁移前后的系统分别检索，计算召回率差异。
$ npx @google/gemini-cli
> 请写一个召回率测试脚本 benchmark_recall.py：
>
> 输入：golden_testset.jsonl（每行一个 dict，包含 query 和 expected_doc_ids）
>
> 处理：
> 1. 对每个 query 分别用 ChromaDB 和 Pinecone 检索 Top-10 结果
> 2. 计算两个系统的 Recall@10 和 MRR@10
> 3. 统计结果分布，输出散点图（横轴 ChromaDB 分数，纵轴 Pinecone 分数）
>
> 输出：
> - recall_comparison.csv
> - mrr_comparison.csv
> - scatter_plot.png
> - summary_report.txt如果召回率出现下降（哪怕是 2-3%），通常需要调整以下参数：
- Top-K 数量：从 Top-10 试 Top-20，看召回是否回升
- Rerank 模型：引入 Cohere Rerank 或 bge-reranker 做二轮重排
- 混合检索权重：BM25 关键词检索 + 向量检索的权重配比（建议从 0.3:0.7 开始调）
- 查询扩展：用 Claude 对原始 query 做改写，提升同义覆盖率
我自己在迁移一个内部知识库 RAG 系统时，遇到了一个非常隐蔽的问题——时间戳精度导致的元数据过滤失效。
问题现象双写阶段一切正常，读取切换到 50% 之后开始收到用户反馈：「为什么搜最近半年的文档，有时候能出来，有时候又没了？」
根因分析ChromaDB 存储的 created_at 元数据是 ISO 8601 字符串格式 "2024-01-15T10:30:00Z"，而 Pinecone 对数值型元数据过滤支持更好，对字符串比较有时会出现语义不一致。我用 Gemini CLI 帮我写了对比脚本才发现这个问题。
$ npx @google/gemini-cli
> 帮我分析这个过滤失效问题：
> ChromaDB 查询：
> where={"created_at": {"$gte": "2024-01-01"}}
>
> 在 Pinecone 中我用同样的语法但数据拿不到，
> 请帮我检查元数据格式并给出解决方案。Gemini CLI 的分析指出：Pinecone 对字符串的 $gte/$lte 比较是按字典序进行的，而非日期语义。建议统一改成 Unix 时间戳格式存储，并更新过滤逻辑。
解决方案# 修改元数据转换函数，统一存储 Unix 时间戳
def transform_datetime_metadata(metadata: dict) -> dict:
if "created_at" in metadata:
import datetime
dt = datetime.fromisoformat(metadata["created_at"].replace("Z", "+00:00"))
metadata["created_at_ts"] = int(dt.timestamp())
del metadata["created_at"] # 删除字符串字段
return metadata
# Pinecone 过滤改用数值比较
filter={"created_at_ts": {"$gte": 1704067200}} # 2024-01-01 00:00:00 UTC回顾整个迁移过程，Gemini CLI 给我最大的感受是：它不是直接给你答案，而是帮你把一个模糊的大问题拆解成一系列可执行的小任务。这种能力在复杂系统迁移中尤为珍贵。
Gemini CLI 最擅长的场景- 代码生成：迁移脚本、接口适配层、验证工具——样板代码让它写，自己改核心逻辑
- 差异分析：两个系统的 API 语义差异，用 Gemini CLI 帮你对照分析
- 问题诊断：遇到报错贴给 Gemini CLI，它能结合上下文给出可能原因和解决方案
- 文档检索：有时候官方文档写得不够清楚，直接问 Gemini CLI 它能给出更实用的示例
- 上下文窗口：项目规模太大时，需要分批喂给它代码，否则会漏掉跨文件的依赖关系
- 执行验证：AI 生成的代码一定要自己跑一遍验证，特别是涉及数据写入的操作
- 最新库版本：Gemini CLI 的知识有截止日期，某些新出的库版本可能没有覆盖到
| 工具 | 用途 |
| Gemini CLI | AI 编程 Agent，驱动整个迁移过程 |
| ChromaDB | 源向量数据库（迁移前） |
| Pinecone | 目标向量数据库（迁移后） |
| Claude Embeddings | 新 Embedding 模型 |
| OpenAI Ada-002 | 旧 Embedding 模型 |
本文涉及的代码示例均为简化版本，生产环境使用请根据实际情况调整。如有问题，欢迎在评论区交流迁移经验。
评论区