RedisVL Playground

基于 RedisVL 构建的交互式向量数据库演示项目，功能包括向量搜索、语义缓存和 LLM 速度对比。

项目结构

backend/
├── main.py              # FastAPI 入口，注册路由，挂载前端
├── api/                 # HTTP 接口层（路由 + 参数校验）
│   ├── index.py         # 索引 CRUD
│   ├── data.py          # 数据读写
│   ├── search.py        # 向量搜索
│   ├── cache.py         # LLM 缓存速度对比
│   └── settings.py      # Redis / DeepSeek 连通性测试
└── services/            # 业务逻辑层
    ├── redis_service.py # 核心服务（索引、数据、搜索、精确缓存）
    └── llm_service.py   # LLM + 语义缓存（Ollama 嵌入、DeepSeek 调用）

架构总览

请求 → API 层（路由 + 校验）→ Service 层（业务逻辑）→ Redis / DeepSeek / Ollama

main.py 将五条路由组装成一个 FastAPI App，统一挂在 /api 前缀下，同时托管前端静态文件。

---

API 层：backend/api/

每个文件只负责接收请求、校验参数、调用 Service、包装错误，不包含业务逻辑。

index.py — 索引管理

端点	方法	功能
/api/index/list	GET	列出所有索引及文档数
/api/index/create	POST	新建索引（名称、前缀、向量维度）
/api/index/drop	DELETE	删除索引
/api/index/status	GET	查询索引状态（是否存在、字段列表、文档数）

data.py — 数据读写

端点	方法	功能
/api/data/load	POST	加载示例数据（自动适配 movie / cache 类型）
/api/data/add	POST	手动添加单条记录，自动生成向量
/api/data/list	GET	列出索引中全部数据

search.py — 向量搜索

端点	方法	功能
/api/search/	POST	输入关键词，返回语义最相似的文档

流程：文本 → Ollama / Hash 嵌入 → Redis KNN 查询 → 返回结果 + 相似度分数。

cache.py — LLM 缓存速度对比

端点	方法	功能
/api/cache/llm-direct	POST	直接调 DeepSeek（无缓存），测量延迟
/api/cache/exact	POST	精确匹配缓存（MD5 哈希键）
/api/cache/semantic	POST	语义缓存（Ollama 嵌入 + 相似度匹配）
/api/cache/clear	POST	清空所有缓存

这是 LLM 速度对比实验的核心：三个缓存策略端点并行调用，前端可直观对比延迟差异。

settings.py — 连接测试

端点	方法	功能
/api/settings/test-redis	GET	Ping Redis，验证连接可用
/api/settings/test-llm	GET	调一次 DeepSeek API，验证 key 和模型

---

Service 层：backend/services/

redis_service.py — 核心服务（~500 行）

职责	说明
索引 CRUD	create_index / drop_index / list_indexes / index_status
示例数据	load_sample_data — 自动识别索引类型（movie / cache），加载对应演示数据
向量搜索	vector_search — 自动发现 Schema 中的向量字段和维度，用 Ollama 真实嵌入（768-dim nomic-embed-text）或哈希伪向量（4-dim）做搜索
手动添加	add_document — 从标题自动生成向量并入库
数据列举	list_data — 兼容 JSON 和 Hash 两种 Redis 存储类型
精确缓存	exact_cache_check / exact_cache_store / exact_cache_clear — 以 MD5(prompt) 为键的 Redis Hash 缓存

这是整个后端的核心，所有索引操作、电影数据、向量搜索和精确缓存都在这里实现。

索引类型自动适配

load_sample_data 根据 Schema 自动判断索引类型并加载对应的示例数据：

索引类型	判断规则	示例数据	向量
movie	有 title + embedding	8 部电影 (Inception, Interstellar …)	4-dim Hash 伪向量
cache	有 prompt + response + prompt_vector	5 组中文 Q&A	768-dim Ollama 真实语义嵌入

llm_service.py — LLM + 语义缓存（~200 行）

职责	说明
Ollama 嵌入	_ollama_embed() — HTTP 调用 Ollama /api/embed 接口，模型 nomic-embed-text，产出 768 维真实语义向量
自定义向量器	_OllamaVectorizer — 继承 BaseVectorizer，包装 Ollama 调用，供 SemanticCache 使用
DeepSeek 调用	direct_llm_call() — 直接调 DeepSeek API 生成回复，返回响应内容和延迟
语义缓存管理	_get_semantic_cache() — 创建/复用 SemanticCache(name="demo-semantic-cache")
	semantic_cache_check() — 查询缓存是否已有语义类似的回答
	semantic_cache_store() — 缓存新的 prompt-response 对
	cached_llm_call() — 完整流程：查缓存 → 未命中调 DeepSeek → 存入缓存

redis_service.py 和 llm_service.py 的区别：

	redis_service.py	llm_service.py
用途	普通搜索索引的向量检索	语义缓存
底层	直接 VectorQuery → Redis KNN	redisvl 的 SemanticCache 类
嵌入	Ollama / Hash 两者皆可	固定 Ollama

---

数据流示例

加载示例数据

前端点击 "加载示例数据"
  → POST /api/data/load
    → RedisService.load_sample_data()
      → _detect_index_type() 判断: movie 还是 cache?
      → _load_movie_data()   → SearchIndex.load(8 部电影)
      → _load_cache_data()   → Ollama 嵌入 + SearchIndex.load(5 组 Q&A)

向量搜索

前端搜索 "redis"
  → POST /api/search/
    → RedisService.vector_search()
      → _discover_vector_field() 自动发现向量字段名
      → 维度 = 768? → Ollama 实时嵌入
      → 维度 ≠ 768? → Hash 伪向量（fallback）
      → VectorQuery → Redis KNN → 返回结果 + score

LLM 速度对比

三种策略并行调用：
  POST /api/cache/llm-direct  → DeepSeek 直接调用（baseline）
  POST /api/cache/exact       → MD5 精确匹配缓存
  POST /api/cache/semantic    → SemanticCache 语义相似度匹配

---

启动项目

./start.sh

服务	端口	说明
Ollama	11435	向量嵌入服务（nomic-embed-text）
Redis	6379	Redis Stack，提供向量搜索与数据存储
Backend (FastAPI)	8000	REST API
Frontend (Vite)	5173	React 前端界面（dev 模式）

---

技术栈

• 后端：FastAPI + RedisVL + redis-py
• 前端：React + TypeScript + Vite
• 向量嵌入：Ollama nomic-embed-text（768-dim，真实语义嵌入）
• LLM：DeepSeek API
• 数据库：Redis Stack（RediSearch 向量搜索）