多模态Embedding流水线实战：基于Gemini Batch API的电商商品向量检索系统

本项目展示如何构建可处理10万+商品的多模态向量生成流水线，利用Google Gemini Embedding 2模型的Batch API能力，以极低成本（仅同步API的一半）实现文本+图像的统一向量表示，并存储到Qdrant向量数据库实现高效检索，解决电商搜索、推荐等场景中的复杂需求。

传统商品搜索依赖关键词匹配，难以处理复杂语义需求（如"找类似红色连衣裙但袖子更短的款式"）。多模态Embedding通过将商品文本描述和图片编码到同一向量空间，实现跨模态语义搜索。本项目以H&M电商数据集（约10.5万件商品，含文本属性和图片）为基础，核心挑战包括：1.数据规模大需高效批处理；2.控制API调用成本；3.长链路ETL的可靠性；4.文本与图像Embedding的有效融合。

流水线采用8阶段设计，数据流向：HuggingFace数据集→数据摄取→图片下载→分片构建→批量提交→Gemini Batch API→结果收集→集合初始化→向量入库→Qdrant向量检索。核心组件：Embedding模型为Gemini Embedding 2（1536维Matryoshka表示）；API模式选择Batch API（节省50%成本）；向量数据库用Qdrant（本地部署，支持HNSW索引和二值量化）；状态管理用SQLite（WAL模式，断点续传）。

Gemini Batch API相比同步调用可享约50%折扣。典型记录（1张图片+约50文本token）的成本对比：1k条同步$0.13 vs Batch ~$0.065；10k条同步$1.3 vs Batch ~$0.65；100k条同步$13 vs Batch ~$6.5；100万条同步$130 vs Batch ~$65。处理10.5万条H&M数据集预估成本约6.8美元，使大规模多模态Embedding在中小型项目可行。

八阶段流水线详情： 1.数据摄取：从HuggingFace加载数据集，写入SQLite状态库，丢弃预计算Embedding列； 2.图片下载：异步HTTP/2客户端并发下载（默认32并发，5次重试），SHA256命名缓存，状态库记录下载状态； 3.分片构建：将待处理记录划分为JSONL分片，含base64编码图片； 4.批量提交：检查Tier1限流（≤43.2万token），控制并发任务数（≤9），轮询状态，失败任务自动重置； 5.结果收集：下载结果，解析Embedding写入Parquet，更新状态库； 6.Qdrant集合初始化：创建hm_products集合，配置1536维余弦相似度、HNSW索引、二值量化、payload关键字索引； 7.向量入库：从Parquet读取向量，UUID5生成ID，批量upsert到Qdrant（默认4并发）； 8.验证：记录数匹配、随机抽样向量质量、自搜索测试、跨模态搜索测试。

关键设计决策： 1.幂等性与断点续传：各阶段幂等，SQLite状态库追踪记录状态，支持中断恢复； 2.限流与配额管理：保守使用Gemini Tier1配额（预留10%缓冲）； 3.确定性ID生成：UUID5基于商品ID生成向量点ID，确保重复运行无重复数据； 4.本地优先架构：Qdrant本地部署，消除云服务按量计费成本。

应用场景： -视觉相似商品推荐：实时检索最近邻推荐相似款式； -跨模态搜索：文字找图片/图片找文字（如街拍找商城商品）； -智能标签生成：自动补全商品属性标签； -重复商品检测：识别重复/高度相似商品。 扩展思路：接入实时数据流支持增量更新；集成轻量模型降低延迟；添加用户行为数据实现个性化重排序。

快速开始步骤： 1.克隆仓库并安装依赖：git clone → cd gemini-multimodal-embeddings → uv sync； 2.配置API密钥：cp .env.example .env → 编辑设置GEMINI_API_KEY； 3.启动本地Qdrant：docker compose up -d； 4.试运行：make pilot（推荐500条测试）； 5.完整运行：make full； 6.检查进度：uv run gme status。 结语：多模态Embedding重塑电商搜索推荐体验，本项目利用Gemini Batch API成本优势，提供支撑10万级商品的技术蓝图，适合相关开发者借鉴。