Redis OM 是 Redis 官方推出的对象映射库，它在 RediSearch、RedisJSON 等模块之上提供了一层类似 ORM 的开发体验。开发者在 Ubuntu 服务器上部署时，如果只安装 apt 默认的 redis-server，很多命令可以执行，但一旦引入对象映射、索引查询或 JSON 文档保存，就会因为缺少模块而失败。因此正确的部署路径是先安装 Redis Stack，再安装对应语言的 redis-om 客户端库。
一、安装并启动 Redis Stack
Redis Stack 是 Redis 官方整合了 RedisJSON、RediSearch、RedisGraph、RedisTimeSeries 等模块的发行版。它的服务端二进制名称通常为 redis-stack-server，安装后可以直接使用与 Redis 一致的协议和命令行工具。对于 Redis OM 这样的对象映射库来说，RediSearch 负责索引创建与条件查询，RedisJSON 负责保存嵌套文档，因此不能只部署基础的 redis-server。
在 Ubuntu 中推荐使用官方 APT 仓库安装，命令如下：
sudo apt-get update sudo apt-get install -y curl gnupg lsb-release curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list sudo apt-get update sudo apt-get install -y redis-stack-server
安装完成后，可以执行 sudo systemctl enable redis-stack-server --now 启动服务并设置开机自启。随后使用 redis-cli 连接本机，执行 MODULE LIST 查看已加载模块。输出中如果包含 ReJSON 和 search，说明对象映射所需的模块已经就绪。
如果希望快速测试，也可以使用 Docker 启动 Redis Stack。但生产环境建议采用 systemd 管理本地服务，避免容器重启后索引数据丢失。无论哪种方式，后续 Python 客户端通过 redis://localhost:6379 连接即可。
二、安装 Redis OM 并定义实体模型
服务端就绪后，创建项目目录并初始化 Python 虚拟环境。安装 redis-om 时建议同时安装 fastapi 和 uvicorn 用于后续验证。执行以下命令：
python3 -m venv venv source venv/bin/activate pip install redis-om fastapi uvicorn
Redis OM Python 提供 JsonModel 和 HashModel 两种基类。JsonModel 使用 RedisJSON 模块保存数据，支持嵌套对象和数组；HashModel 使用传统 Hash 存储，字段结构更扁平。需要持久化订单、用户资料等复杂结构时，选择 JsonModel 更合适。
下面的实体类定义了创建时间默认值，并把 order_no、customer_id、status 三个字段声明为索引字段。Redis OM 会根据索引字段生成 RediSearch 查询条件。
from redis_om import JsonModel, Field
from datetime import datetime
from typing import Optional
class Order(JsonModel):
order_no: str = Field(index=True)
customer_id: str = Field(index=True)
amount: float
status: str = Field(index=True)
created_at: datetime = Field(default_factory=datetime.now)
note: Optional[str] = None
class Meta:
model_key_prefix = "order"
实体模型定义完成后，并不需要手工编写建表或索引语句。Redis OM 在运行时通过 Migrator 读取模型元数据，自动在 Redis 中创建对应的索引结构。这种设计减少了部署过程中的配置工作量，尤其适合实体数量较多的系统。
三、执行插入、查询与搜索操作
在保存数据之前，需要先运行 Migrator().run() 来创建索引。此后每次实例化实体并调用 save() 方法，Redis OM 会自动完成序列化、写入以及索引更新。读取数据时既可以使用主键精确获取，也可以通过字段条件筛选。
import asyncio
from redis_om import Migrator
from models import Order
async def main():
Migrator().run()
order = Order(
order_no="SO-20250201-001",
customer_id="C1001",
amount=369.50,
status="pending"
)
await order.save()
loaded = await Order.get(order.pk)
print(loaded.amount)
results = await Order.find(Order.status == "pending").all()
print(len(results))
asyncio.run(main())
Order.find() 返回一个查询构造器，支持字段相等、范围、模糊匹配等条件。查询结果支持 sort_by() 排序和 page() 分页，避免一次性拉取大量数据。比如可以先按创建时间倒序排列，再只读取前 20 条记录，这对订单列表接口非常实用。
与直接使用 redis-cli 拼装 FT.SEARCH 命令相比，Redis OM 的查询表达式更贴近 Python 语法，类型提示和 IDE 补全也能帮助开发者减少拼写错误。对象映射层负责把复杂查询转换成底层 RediSearch 命令，业务代码保持清晰易读。
四、使用 FastAPI 验证对象映射
为了更直观地验证部署结果，可以构建一个简单的 FastAPI 服务，对外提供订单创建和查询接口。FastAPI 接收 JSON 请求体后，将字段传递给 Order 实体，保存成功后返回主键；查询接口则根据 status 参数返回符合条件的订单列表。
from fastapi import FastAPI
from pydantic import BaseModel
from redis_om import JsonModel, Field, Migrator
from datetime import datetime
from typing import Optional
app = FastAPI()
Migrator().run()
class OrderPayload(BaseModel):
order_no: str
customer_id: str
amount: float
status: str
note: Optional[str] = None
class Order(JsonModel):
order_no: str = Field(index=True)
customer_id: str = Field(index=True)
amount: float
status: str = Field(index=True)
created_at: datetime = Field(default_factory=datetime.now)
note: Optional[str] = None
class Meta:
model_key_prefix = "order"
@app.post("/orders")
async def create_order(payload: OrderPayload):
order = Order(**payload.dict())
await order.save()
return {"pk": order.pk, "saved": True}
@app.get("/orders")
async def list_orders(status: str = "pending"):
orders = await Order.find(Order.status == status).all()
return [order.dict() for order in orders]
启动服务时执行 uvicorn main:app --host 0.0.0.0 --port 8000。使用 curl 向 /orders 接口发送 POST 请求插入一条订单，再请求 /orders?status=pending 即可看到刚才写入的数据被正确返回。整个调用链路中，开发者不需要手动操作 JSON 序列化和 Redis 命令，对象映射已经封装了这些细节。
验证完成后，建议进一步关注索引更新、连接池配置和 Redis 内存淘汰策略。对象映射简化了写入与查询逻辑，但生产环境仍需要根据业务规模调整 redis-stack-server 的持久化参数和资源限制，确保数据安全与查询性能达到预期。