redis-product-search
Redis 官方向量搜索演示：基于 Redis Stack + FastAPI + React 实现以图搜图与语义商品检索
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
Redis 官方向量搜索演示：基于 Redis Stack + FastAPI + React 实现以图搜图与语义商品检索
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你有没有过这样的体验：在淘宝输入"轻薄透气的长裙"，即使商品标题里根本没有这几个字，系统依然能精准返回符合你心意的宝贝？这种"语义搜索"能力背后，依赖的核心技术正是向量相似度搜索（Vector Similarity Search, VSS）。
redis-developer/redis-product-search 是 Redis 官方出品的向量搜索演示项目，通过这个开源 Demo，开发者可以亲自动手，理解向量数据库如何在真实电商场景中实现"以图搜图"和"语义搜索"。与其看官方文档里抽象的概念解释，不如直接跑这个项目，用眼睛看到效果——这正是这个 Demo 的价值所在。
Redis 最初以"超快的内存键值数据库"闻名，但在 2023 年推出的 Redis Stack 7.4 中，Redis 通过内置的 RediSearch 模块正式支持了向量搜索能力。这一能力的加入让 Redis 从"纯内存数据库"进化为"内存优先的向量数据库"，在亚毫秒级延迟下完成高维向量检索。
这个 Demo 由 Redis 官方开发者维护（redis-developer 组织），是 Redis 官方推荐的向量搜索入门项目。它的定位是"教学级演示"，代码结构清晰、注释丰富，同时又有一定的工程复杂度——既适合初次接触向量搜索的开发者快速上手，也能作为企业构建生产级向量搜索系统的参考架构。
向量搜索的基本思想是：将文字、图片等非结构化数据，通过 embedding 模型转换为高维向量（如 512 维、768 维的浮点数数组），然后在向量空间中计算"距离"来找到最相似的结果。
在这个 Demo 中，使用了两类 embedding 模型：
img2vec 库，将商品图片编码为 512 维向量，支持"以图搜图"功能Redis 在底层使用两种索引算法来加速向量检索：
单纯依靠向量相似度搜索往往不够精确——比如用户搜索"男款运动鞋"，向量搜索可能返回大量女款休闲鞋。Demo 实现的"混合查询"正是解决这个问题的标准方案：通过 Redis 的 Tag 字段（gender、category）做第一层过滤，再在过滤后的子集中执行向量搜索，既保证了语义相关性，又精确限制了商品范围。
商品数据通过 load.py 脚本从 AWS S3 读取 JSON 文件，包含商品元数据（ID、名称、性别、类别、图片URL）以及预计算好的图像向量和文本向量。加载过程中，数据经过预处理后批量写入 Redis，每个商品的向量数据以二进制 blob 格式存储，节省内存占用。
后端采用 FastAPI 框架，通过 redisvl（Redis 官方向量数据库 Python 客户端）与 Redis 交互。RedisVL 是 Redis 官方维护的高级客户端，封装了索引创建、向量写入、向量查询等操作，比直接使用底层命令更加便捷和安全。
核心 API 路由定义在 backend/productsearch/api/routes/product.py 中，提供以下接口：
GET / —— 按性别和类别过滤获取商品列表（纯结构化查询）POST /vectorsearch/image —— 以图搜图，通过上传图片获取相似商品POST /vectorsearch/text —— 语义搜索，输入文本获取语义相关商品FastAPI 的异步架构与 RedisVL 的 AsyncSearchIndex 配合，使得每个请求可以在不阻塞的情况下处理多个并发查询，整体吞吐量远高于同步方案。
前端是标准的 React TypeScript 单页应用，通过 api.ts 中的 HTTP 客户端调用后端接口。构建产物通过 FastAPI 的静态文件服务直接托管（templates/build 目录），无需独立的前端服务器，实现了真正的"前后端合一"部署。
用户在前端输入搜索词 → 前端将搜索词 POST 到后端 → 后端调用 HuggingFace Sentence Transformers 生成文本向量 → 向量发送给 Redis 执行 HNSW 检索 → Redis 返回相似商品 ID 和向量距离 → 后端组装商品元数据 → 前端渲染卡片展示。整个链路的端到端延迟在网络良好的情况下可以控制在 100ms 以内。
这是该项目最值得称赞的工程实践之一。只需要一条命令：
make build
# 或者
docker compose -f docker-local-redis.yml up
Docker Compose 会自动拉取 Redis Stack 镜像（包含 RediSearch 模块）和应用镜像，完成环境搭建、数据初始化、数据库索引构建的全过程。开发者无需手动安装 Python 依赖、配置 Redis 参数或准备样本数据，开箱即用。
Dockerfile 采用了 Node.js + Python 的多阶段构建策略：前端通过 node:22.0-alpine 构建 React 生产包，后端通过 python:3.11-slim-buster 运行 FastAPI，两个镜像在运行时通过 Docker 网络互联，实现了前后端的完全隔离。
硬件需求方面，该项目不需要 GPU——向量 embedding 阶段使用的是预计算好的向量数据（在 products.json 中已包含），而不是在线计算。这意味着任何一台 4GB+ 内存的普通服务器都能运行。Redis Stack 本身运行在内存中，Demo 的 ~5500 条商品数据（每条包含 512 维图像向量 + 768 维文本向量，总计约 1280 维 float32）大约占用 30-50MB 内存。
尽管 Demo 非常优秀，仍有几个值得注意的限制：
向量预计算限制：当前版本的商品向量是预计算好的（存储在 products.json 中），意味着如果要添加新商品，开发者需要自行调用 embedding 模型重新生成向量，再导入 Redis。这在生产环境中需要一个独立的 embedding 服务来处理动态新增的数据。
数据规模：Demo 使用约 5500 条商品数据，这个规模对于演示来说恰到好处，但远不足以体现 Redis 在百万级甚至千万级向量数据下的真实性能。如果要评估 Redis 在生产级规模下的表现，需要自行准备更大规模的数据集。
安全配置：后端的 CORS 配置为 allow_origins="*"，生产环境部署时需要修改为具体的域名白名单。Redis 密码也通过环境变量注入，在生产环境中建议使用 Docker Secret 或外部密钥管理服务。
非中文优化：HuggingFace Sentence Transformers 默认模型（如 all-MiniLM-L6-v2）对英文语义理解效果出色，但对中文的支持相对有限。如果要构建中文电商搜索系统，需要替换为支持中文的 embedding 模型（如 moka-ai/m3e-base）。
向量数据库是 2023-2024 年 AI 基础设施领域最热门的赛道之一，吸引了 Pinecone、Weaviate、Qdrant、Chroma 等一批专业玩家的入场。Redis 的优势在于：开发者无需学习新的数据库系统，利用现有的 Redis 技能栈就能快速构建向量搜索能力。对于已经在使用 Redis 作为缓存或主数据库的团队来说，这是一种零迁移成本的向量搜索扩展路径。
这个 Demo 项目的 star 增长趋势也印证了市场热度：随着大语言模型（LLM）的爆火，RAG（检索增强生成）架构中对向量数据库的需求急剧增长，越来越多的开发者开始学习向量搜索技术，Redis 作为"最熟悉的陌生数据库"，正在这个新赛道上找到自己的位置。
如果你想尝试这个项目，建议的路径是：
docker compose up，等 Redis 和应用启动完成http://localhost:8888，体验以图搜图和语义搜索backend/productsearch/api/routes/product.py，理解向量查询的 API 设计backend/productsearch/db/schema/products.yml，理解 Redis 向量索引的 schema 定义load.py 的逻辑接入自己的商品数据总体来说，这是一个工程质量和教育价值都很高的官方 Demo，既适合作为向量搜索的入门教材，也可作为构建生产级电商搜索系统的架构参考。