七、编写 Dockerfile

在项目根目录创建 Dockerfile：

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

RUN apt update && apt install -y \
    gcc \
    curl \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .

RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]

如果你在海外服务器上部署，可以改为默认 PyPI：

RUN pip install --no-cache-dir -r requirements.txt

八、编写 Docker Compose 配置

创建 docker-compose.yml：

services:
  ai-agent:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ai-agent
    restart: always
    env_file:
      - .env
    ports:
      - "8000:8000"
    volumes:
      - ./logs:/app/logs
    depends_on:
      - postgres
      - redis
      - qdrant
    networks:
      - agent-net

  postgres:
    image: postgres:16
    container_name: agent-postgres
    restart: always
    environment:
      POSTGRES_DB: agent_db
      POSTGRES_USER: agent_user
      POSTGRES_PASSWORD: replace_with_strong_password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - agent-net

  redis:
    image: redis:7
    container_name: agent-redis
    restart: always
    command: redis-server --appendonly yes
    volumes:
      - redis-data:/data
    ports:
      - "6379:6379"
    networks:
      - agent-net

  qdrant:
    image: qdrant/qdrant:v1.11.5
    container_name: agent-qdrant
    restart: always
    volumes:
      - qdrant-data:/qdrant/storage
    ports:
      - "6333:6333"
      - "6334:6334"
    networks:
      - agent-net

networks:
  agent-net:
    driver: bridge

volumes:
  postgres-data:
  redis-data:
  qdrant-data:

建议将 PostgreSQL、Redis、Qdrant 的端口只暴露给内网或干脆不暴露到宿主机，生产环境可以改成：

ports: []

或删除对应 ports 配置，仅允许容器内部访问。

九、启动 AI Agent 服务

构建镜像：

docker compose build

启动服务：

docker compose up -d

查看容器状态：

docker compose ps

查看日志：

docker compose logs -f ai-agent

测试健康检查接口：

curl http://127.0.0.1:8000/health

正常返回：

{
  "status": "ok",
  "service": "AI Agent Service",
  "env": "production"
}

测试聊天接口：

curl -X POST http://127.0.0.1:8000/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: replace_with_your_internal_api_key" \
  -d '{
    "user_id": "u001",
    "message": "请介绍一下什么是 AI Agent"
  }'

十、配置 Nginx 反向代理

生产环境不建议直接暴露 8000 端口，而是通过 Nginx 暴露 80/443。

安装 Nginx：

apt install -y nginx

创建配置文件：

vim /etc/nginx/sites-available/ai-agent.conf

写入：

server {
    listen 80;
    server_name agent.example.com;

    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 300;
        proxy_connect_timeout 60;
        proxy_send_timeout 300;
    }
}

启用站点：

ln -s /etc/nginx/sites-available/ai-agent.conf /etc/nginx/sites-enabled/

检查配置：

nginx -t

重载 Nginx：

systemctl reload nginx

访问：

curl http://agent.example.com/health

十一、配置 HTTPS 证书

生产环境必须启用 HTTPS。推荐使用 Certbot 申请 Let’s Encrypt 免费证书。

安装 Certbot：

apt install -y certbot python3-certbot-nginx

申请证书：

certbot --nginx -d agent.example.com

查看证书自动续期状态：

systemctl status certbot.timer

手动测试续期：

certbot renew --dry-run

HTTPS 测试：

curl https://agent.example.com/health

十二、日志与可观测性

AI Agent 生产环境中，日志非常重要。你需要记录：

• 用户请求 ID
• 用户 ID
• 请求时间
• 模型名称
• Token 消耗
• 工具调用记录
• 向量检索结果
• 错误堆栈
• 响应耗时
• 失败重试次数

示例日志工具 app/utils/logger.py：

from loguru import logger

logger.add(
    "logs/app.log",
    rotation="100 MB",
    retention="30 days",
    encoding="utf-8"
)

app_logger = logger

在业务代码中使用：

from app.utils.logger import app_logger

app_logger.info("Agent request received")
app_logger.error("LLM call failed")

查看日志：

tail -f logs/app.log

查看 Docker 日志：

docker logs -f ai-agent

清理无用 Docker 日志和镜像：

docker system prune -f

十三、Redis 用于会话与缓存

AI Agent 常常需要保存短期上下文，例如多轮对话状态。Redis 可以用于：

• 会话缓存
• 限流计数
• 工具调用结果缓存
• 异步任务状态
• 防重复请求

安装 Redis 依赖已经包含在 requirements.txt 中。示例代码：

import redis
from app.config import settings

redis_client = redis.Redis(
    host=settings.REDIS_HOST,
    port=settings.REDIS_PORT,
    db=0,
    decode_responses=True
)


def save_session(user_id: str, message: str):
    key = f"session:{user_id}"
    redis_client.rpush(key, message)
    redis_client.expire(key, 3600)


def get_session(user_id: str):
    key = f"session:{user_id}"
    return redis_client.lrange(key, 0, -1)

进入 Redis 容器：

docker exec -it agent-redis redis-cli

查看 key：

keys *

查看某个会话：

lrange session:u001 0 -1

十四、向量数据库与 RAG 部署

如果你的 AI Agent 需要企业知识库问答，就需要 RAG（Retrieval-Augmented Generation，检索增强生成）。
常见流程是：

文档上传
   ↓
文本切分
   ↓
Embedding 向量化
   ↓
写入向量数据库
   ↓
用户提问
   ↓
向量检索
   ↓
拼接上下文
   ↓
调用大模型生成答案

Qdrant 已经在 Compose 中启动，可以测试：

curl http://127.0.0.1:6333/collections

创建集合示例：

curl -X PUT http://127.0.0.1:6333/collections/company_docs \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {
      "size": 1536,
      "distance": "Cosine"
    }
  }'

查看集合：

curl http://127.0.0.1:6333/collections/company_docs

如果使用不同 Embedding 模型，size 需要根据模型维度调整。例如：

十五、数据库初始化与数据持久化

PostgreSQL 用于保存业务数据，例如：

• 用户信息
• 会话记录
• Agent 执行轨迹
• 工具调用日志
• 任务状态
• 账单与 Token 消耗

进入 PostgreSQL 容器：

docker exec -it agent-postgres psql -U agent_user -d agent_db

创建示例表：

CREATE TABLE agent_requests (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(128) NOT NULL,
    message TEXT NOT NULL,
    answer TEXT,
    model_name VARCHAR(128),
    latency_ms INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

查看表：

\dt

退出：

\q

备份数据库：

docker exec agent-postgres pg_dump -U agent_user agent_db > backup_agent_db.sql

恢复数据库：

cat backup_agent_db.sql | docker exec -i agent-postgres psql -U agent_user -d agent_db

十六、接口安全与权限控制

生产环境中的 AI Agent 必须做好安全控制。至少需要考虑以下几点：

1. API Key 鉴权

本文示例已通过 X-API-Key 做了基础鉴权。但真实生产环境中，建议使用：

• JWT
• OAuth2
• 企业 SSO
• 内部网关签名
• IP 白名单

2. 限流

可以在 Nginx 层添加限流：

limit_req_zone $binary_remote_addr zone=agent_limit:10m rate=10r/s;

server {
    listen 80;
    server_name agent.example.com;

    location / {
        limit_req zone=agent_limit burst=20 nodelay;
        proxy_pass http://127.0.0.1:8000;
    }
}

检查并重载：

nginx -t
systemctl reload nginx

3. Prompt 注入防护

AI Agent 容易受到 Prompt Injection 攻击，例如用户要求模型“忽略之前的系统提示词”。应采取：

• 系统提示词与用户输入严格分离
• 工具调用权限校验
• 敏感操作二次确认
• 不让模型直接拼接 SQL
• 对外部网页内容进行不可信标记
• 对工具参数做 schema 校验

4. 敏感信息保护

不要把以下内容直接传给模型：

• 用户身份证号
• 手机号
• 银行卡
• 内部密钥
• 数据库密码
• 未脱敏客户数据

十七、生产环境性能优化

AI Agent 服务的性能瓶颈通常来自模型调用，而不是 Web 框架本身。常见优化方式包括：

1. 设置超时

ChatOpenAI(
    timeout=30,
    max_retries=2
)

2. 使用缓存

对于重复问题，可以缓存回答：

问题 Hash → Redis → 命中则直接返回

3. 降低上下文长度

不要把所有历史对话都塞进模型，应使用：

• 滑动窗口
• 摘要记忆
• 长期记忆检索
• 用户画像压缩

4. 并发控制

如果模型 API 有速率限制，需要限制并发请求。可以使用队列或信号量。

5. 模型分级

不同任务使用不同模型：

这样可以显著降低成本。

十八、部署本地模型：Ollama 示例

如果你希望将模型部署在本地，可以使用 Ollama。

安装 Ollama：

curl -fsSL https://ollama.com/install.sh | sh

启动服务：

systemctl enable ollama
systemctl start ollama

拉取模型：

ollama pull qwen2.5:7b

测试模型：

ollama run qwen2.5:7b

调用 API：

curl http://127.0.0.1:11434/api/generate \
  -d '{
    "model": "qwen2.5:7b",
    "prompt": "请解释什么是 AI Agent",
    "stream": false
  }'

如果 FastAPI 容器要访问宿主机 Ollama，可以将 OPENAI_BASE_URL 替换为兼容接口，或使用支持 Ollama 的 LangChain 组件。

十九、服务升级与回滚

上线后经常需要发布新版本。推荐流程：

git pull origin main
docker compose build ai-agent
docker compose up -d ai-agent
docker compose logs -f ai-agent

如果新版本出现问题，可以回滚到上一个 Git 版本：

git log --oneline
git checkout 
docker compose build ai-agent
docker compose up -d ai-agent

查看服务是否正常：

curl https://agent.example.com/health

二十、常用运维命令汇总

查看所有容器：

docker ps -a

重启 AI Agent：

docker compose restart ai-agent

停止所有服务：

docker compose down

停止并删除数据卷，谨慎使用：

docker compose down -v

查看资源占用：

docker stats

查看端口占用：

netstat -tunlp

或：

ss -tunlp

查看磁盘空间：

df -h

查看目录大小：

du -sh /opt/ai-agent/*

查看系统内存：

free -h

查看 CPU 负载：

top

查看最近系统日志：

journalctl -xe

查看 Nginx 日志：

tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

二十一、生产环境上线检查清单

上线前建议逐项确认：

• [ ] 服务已容器化部署
• [ ] .env 未提交到 Git
• [ ] API 已开启鉴权
• [ ] HTTPS 已配置
• [ ] Nginx 已设置超时和限流
• [ ] 数据库和向量库已持久化
• [ ] 日志已落盘
• [ ] 模型调用已设置超时和重试
• [ ] 敏感信息已脱敏
• [ ] 工具调用有权限校验
• [ ] 数据库已配置备份策略
• [ ] Redis 不对公网暴露
• [ ] PostgreSQL 不对公网暴露
• [ ] Qdrant 不对公网暴露
• [ ] 已配置健康检查接口
• [ ] 已准备回滚方案
• [ ] 已进行压力测试

二十二、总结

AI Agent 的生产环境部署，重点不在于“能不能调用大模型”，而在于是否具备稳定、安全、可观测、可维护的工程能力。一个真正可上线的 AI Agent 至少需要解决以下问题：

1. 服务化：通过 FastAPI 等框架提供标准 API；
2. 容器化：使用 Docker Compose 或 Kubernetes 管理服务；
3. 数据持久化：PostgreSQL、Redis、向量数据库都要做好持久化；
4. 安全控制：API 鉴权、限流、Prompt 注入防护、敏感信息脱敏；
5. 可观测性：日志、监控、调用链、Token 成本追踪；
6. 稳定性：超时、重试、降级、缓存、回滚机制；
7. 成本优化：模型分级、缓存、减少上下文长度、控制并发。

如果你的 AI Agent 只是内部小范围使用，Docker Compose 已经足够；如果面向大量用户或复杂业务场景，建议进一步升级到 Kubernetes，并引入 Prometheus、Grafana、Loki、Jaeger 等完整可观测体系。

最终，一个优秀的 AI Agent 不是“Prompt 写得好”就够了，而是需要模型能力、业务逻辑、系统架构和工程治理共同配合。只有这样，Agent 才能从实验室走向真正的生产环境。