AI+零售应用教程：用Docker搭一套商品推荐服务

想在零售场景里用上 AI，最直接的切口不是复杂的预测模型，而是一个能跑起来的商品推荐接口。
这篇教程面向零基础用户，用 Docker 搭一个基于协同过滤的推荐服务，你只需要会复制命令和改几个配置项，就能在本地或测试服务器上看到推荐结果。

先确认你的环境能跑容器

这个方案依赖 Docker，推荐在 Linux 服务器或本地虚拟机里操作。
Windows 和 macOS 也能用，但路径和权限细节会有差异，新手优先选 Ubuntu 22.04 或同类发行版。

先检查 Docker 是否可用：

docker --version
docker compose version

两条命令都能输出版本号，说明环境就绪。
如果提示 command not found，先按官方文档装好 Docker Engine 和 Compose 插件，再回来继续。
这里不展开安装步骤，避免不同发行版的源配置把新手带偏。

另外确认 8000 端口没有被占用：

ss -tlnp | grep 8000

有输出就换一个端口，后面启动命令里的 8000:8000 左侧改成空闲端口即可。

准备推荐服务的最小文件结构

新建一个目录，比如 /opt/retail-ai，在里面放三个文件：Dockerfile、requirements.txt、app.py。
下面给的是最小可运行版本，逻辑是读取一份商品评分表，用物品相似度给目标用户推荐没买过的商品。

requirements.txt 内容：

fastapi==0.110.0
uvicorn==0.29.0
pandas==2.2.1
scikit-learn==1.4.1

版本号写死是为了避免依赖漂移，如果安装时报错，优先检查 Python 版本是否匹配，而不是盲目升级。

app.py 的核心逻辑：

from fastapi import FastAPI
import pandas as pd
from sklearn.metrics.pairwise import cosine_similarity

app = FastAPI()

# 示例评分数据：user_id, item_id, rating
ratings = pd.DataFrame([
    (1, 'A', 5), (1, 'B', 3), (1, 'C', 4),
    (2, 'A', 4), (2, 'C', 5), (2, 'D', 2),
    (3, 'B', 5), (3, 'D', 4), (3, 'E', 3),
], columns=['user_id', 'item_id', 'rating'])

pivot = ratings.pivot_table(index='user_id', columns='item_id', values='rating').fillna(0)
sim = cosine_similarity(pivot.T)
sim_df = pd.DataFrame(sim, index=pivot.columns, columns=pivot.columns)

@app.get('/recommend/{user_id}')
def recommend(user_id: int):
    if user_id not in pivot.index:
        return {'error': 'user not found'}
    user_ratings = pivot.loc[user_id]
    scores = sim_df.dot(user_ratings).div(sim_df.sum(axis=1))
    scores = scores[user_ratings == 0].sort_values(ascending=False)
    return {'user_id': user_id, 'recommend': scores.head(3).index.tolist()}

这段代码用余弦相似度算商品之间的接近程度，再给用户打分排序。
它适合做演示和接口联调，真实零售数据量上去后要换成更合适的模型或离线计算，但作为起步足够。

Dockerfile 内容：

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

构建镜像并启动容器

进入 /opt/retail-ai 目录，执行：

docker build -t retail-recommend:0.1 .

构建完成后启动：

docker run -d --name retail-rec -p 8000:8000 retail-recommend:0.1

用 docker ps 确认容器状态是 Up。
如果状态反复重启，用 docker logs retail-rec 看报错，常见原因是依赖安装失败或端口冲突，按日志提示处理，不要直接删容器重来。

调用接口验证推荐结果

服务跑起来后，用 curl 测试：

curl http://127.0.0.1:8000/recommend/1

预期返回类似：

{"user_id":1,"recommend":["D","E"]}

具体推荐商品取决于你的评分数据，只要返回的是该用户没评分过的商品，并且顺序稳定，就说明接口工作正常。
再测一个不存在的用户：

curl http://127.0.0.1:8000/recommend/999

应返回 user not found，这能帮你确认异常分支没有被吞掉。

几个新手容易踩的坑

第一，不要用 latest 标签拉基础镜像。python:3.11-slim 这类带版本号的标签更可控，出现构建差异时容易定位。

第二，评分数据不要直接写死在代码里长期使用。
演示可以，接入真实业务时至少改成挂载 CSV 文件或从数据库读取，否则每次更新商品都要重新构建镜像。

第三，容器内服务必须监听 0.0.0.0。
如果写成 127.0.0.1，端口映射到宿主机后仍然访问不到，这是很常见的“容器起来了但接口不通”的原因。

第四，修改代码后记得重新构建镜像再启动新容器，直接重启旧容器不会加载新代码。

怎么判断这套服务可以继续往下用

接口能返回稳定推荐结果只是第一步。
你可以用同一份评分数据跑两次请求，对比返回顺序是否一致；
再手动构造一个用户，检查推荐列表里是否排除了已购商品。
这两项通过后，再把评分表换成你零售场景里的真实样例数据，观察接口响应时间是否在可接受范围。
如果数据量明显变大导致响应变慢，优先考虑把相似度计算改成离线任务，而不是在接口里硬扛。

这套 AI+零售应用教程的重点不是模型多复杂，而是先把推荐能力以接口形式跑通，后续再逐步替换数据和算法。
遇到异常时，先看容器日志和接口返回，再回看上面的避坑项，多数问题能自己定位。