Agent生产部署：50个必查项

将Agent从Demo推向生产环境，是一个系统工程。以下Checklist基于我们对30+企业Agent项目的实践总结，覆盖了生产部署必须检查的50个关键项。

十大维度概览

维度检查项数优先级
1. 安全与权限7🔴 必须
2. 性能与延迟5🔴 必须
3. 成本控制5🟡 重要
4. 监控与告警6🔴 必须
5. 容错与恢复5🔴 必须
6. 数据与隐私5🔴 必须
7. 质量保障5🟡 重要
8. 可扩展性4🟡 重要
9. 用户体验4🟢 建议
10. 文档与运维4🟢 建议

1. 安全与权限（7项）

✅ 1.1 LLM输出过滤

# 必须对LLM输出进行安全过滤
class OutputFilter:
    def __init__(self):
        self.blocked_patterns = [
            r"忽略.*指令",       # 越狱尝试
            r"system\s*prompt",  # 系统提示词泄漏
            r"<script.*>",       # XSS攻击
        ]
    
    def filter(self, output: str) -> str:
        for pattern in self.blocked_patterns:
            output = re.sub(pattern, "[FILTERED]", output, flags=re.IGNORECASE)
        return output

检查：LLM输出是否经过安全过滤？是否检测了越狱尝试、提示注入、敏感信息泄漏？

✅ 1.2 输入消毒

检查：用户输入是否经过消毒？是否防止了提示注入攻击？

def sanitize_input(user_input: str) -> str:
    # 限制输入长度
    if len(user_input) > 10000:
        user_input = user_input[:10000]
    
    # 移除特殊控制字符
    user_input = re.sub(r'[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]', '', user_input)
    
    # 检测提示注入
    injection_patterns = [
        "ignore previous instructions",
        "你是一个新的AI",
        "忘记你的指令",
    ]
    for pattern in injection_patterns:
        if pattern.lower() in user_input.lower():
            raise SecurityException(f"检测到可能的提示注入: {pattern}")
    
    return user_input

✅ 1.3 工具权限控制

检查：Agent的工具调用是否受到权限控制？是否遵循最小权限原则？

# 基于角色的工具访问控制
TOOL_PERMISSIONS = {
    "viewer": ["search", "read"],
    "editor": ["search", "read", "write", "comment"],
    "admin": ["*"]  # 所有权限
}

def check_tool_permission(user_role: str, tool_name: str) -> bool:
    allowed = TOOL_PERMISSIONS.get(user_role, [])
    return "*" in allowed or tool_name in allowed

✅ 1.4 API密钥管理

检查：API密钥是否存储在密钥管理服务中？是否定期轮换？是否不在代码和日志中出现？

✅ 1.5 代码执行沙箱

检查：如果Agent可以执行代码，是否在隔离的Docker容器中执行？是否限制了网络访问、内存和CPU？

✅ 1.6 速率限制

检查：是否对单用户和全局设置了请求速率限制？

# 速率限制配置
RATE_LIMITS = {
    "per_user": {"requests": 50, "window": "1m"},    # 每用户每分钟50次
    "per_user_daily": {"requests": 1000, "window": "1d"},  # 每用户每天1000次
    "global": {"requests": 5000, "window": "1m"},     # 全局每分钟5000次
    "tool_calls": {"requests": 100, "window": "1m"},  # 工具调用每分钟100次
}

✅ 1.7 审计日志

检查：所有Agent决策和工具调用是否有审计日志？日志是否不可篡改？

2. 性能与延迟（5项）

✅ 2.1 端到端延迟目标

检查：是否定义了延迟SLA？是否监控了P50/P95/P99延迟？

场景P50目标P95目标P99目标
简单问答<1s<3s<5s
工具调用<3s<8s<15s
多步推理<10s<30s<60s

✅ 2.2 流式响应

检查：是否使用流式响应减少用户感知延迟？

# 流式输出
async def stream_response(agent, query):
    async for chunk in agent.astream(query):
        yield chunk  # 每个chunk立即发送给用户
    
    # 用户看到第一个token的时间从3s降低到0.3s

✅ 2.3 并行化

检查：独立的子任务是否并行执行？

✅ 2.4 缓存策略

检查：对相同或相似查询是否启用了缓存？缓存命中率是否监控？

# 语义缓存：相似问题命中缓存
class SemanticCache:
    def __init__(self, threshold=0.95):
        self.threshold = threshold
        self.cache = {}  # {embedding: response}
    
    async def get(self, query: str) -> str | None:
        query_emb = await self._embed(query)
        for emb, response in self.cache.items():
            if self._cosine_sim(query_emb, emb) > self.threshold:
                return response
        return None
    
    async def set(self, query: str, response: str):
        emb = await self._embed(query)
        self.cache[emb] = response

✅ 2.5 模型选型优化

检查：是否根据任务复杂度选择合适大小的模型？简单任务是否使用了小模型？

3. 成本控制（5项）

✅ 3.1 Token预算

检查：是否设置了单次请求和每日token预算？

class TokenBudget:
    def __init__(self):
        self.per_request_limit = 50000    # 单次请求最多50K tokens
        self.daily_limit = 10_000_000     # 每日10M tokens
        self.daily_used = 0
        self.alert_threshold = 0.8        # 80%时告警
    
    def check(self, estimated_tokens: int) -> bool:
        if estimated_tokens > self.per_request_limit:
            return False
        if self.daily_used + estimated_tokens > self.daily_limit:
            return False
        return True
    
    def consume(self, actual_tokens: int):
        self.daily_used += actual_tokens
        if self.daily_used > self.daily_limit * self.alert_threshold:
            self._send_alert()

✅ 3.2 成本归因

检查：能否追踪每个请求、每个Agent、每个用户的成本？

✅ 3.3 模型路由

检查：是否根据任务类型自动路由到成本最优的模型？

✅ 3.4 上下文压缩

检查：长对话是否自动压缩上下文以减少token消耗？

✅ 3.5 成本告警

检查：是否设置了日/小时成本上限告警？超限是否自动降级或停止服务？

4. 监控与告警（6项）

✅ 4.1 核心指标看板

检查：是否有实时监控看板展示核心指标（请求量、成功率、延迟、token消耗、成本）？

✅ 4.2 分布式追踪

检查：Agent执行链路是否可追踪？能否定位到具体哪个Agent/工具/LLM调用导致了问题？

✅ 4.3 错误分类

检查：错误是否按类型分类统计？

ERROR_TYPES = {
    "llm_timeout": "LLM调用超时",
    "llm_rate_limit": "LLM限流",
    "tool_failure": "工具调用失败",
    "context_overflow": "上下文溢出",
    "max_iterations": "达到最大迭代次数",
    "invalid_output": "输出格式无效",
    "safety_filter": "安全过滤触发",
    "budget_exceeded": "预算超限",
}

✅ 4.4 用户反馈追踪

检查：是否收集用户反馈（赞/踩/评分）并关联到具体请求？

✅ 4.5 告警规则

检查：是否配置了以下告警？

  • 错误率 > 10%（5分钟窗口）
  • P95延迟 > 5秒
  • 成功率 < 85%
  • 每小时成本 > ¥100
  • 工具失败率 > 15%

✅ 4.6 在线评估

检查：是否有自动化的在线质量评估（如使用LLM-as-Judge定期评估输出质量）？

5. 容错与恢复（5项）

✅ 5.1 LLM调用重试

检查：LLM调用是否有指数退避重试机制？

@retry(
    max_attempts=3,
    backoff_base=1.0,    # 基础等待1秒
    backoff_factor=2,    # 指数退避
    exceptions=(TimeoutError, RateLimitError)
)
async def call_llm(prompt: str) -> str:
    return await llm.complete(prompt)

✅ 5.2 模型降级

检查：主模型不可用时是否自动降级到备用模型？

FALLBACK_CHAIN = [
    ("gpt-4o", "azure-openai"),
    ("claude-sonnet-4", "anthropic"),
    ("qwen-turbo", "aliyun"),
]

✅ 5.3 熔断机制

检查：错误率过高时是否触发熔断，停止处理新请求？

✅ 5.4 状态持久化

检查：Agent执行状态是否持久化？服务重启后能否恢复？

✅ 5.5 超时兜底

检查：所有操作是否有超时设置？超时后是否有兜底响应？

TIMEOUTS = {
    "llm_call": 30,        # LLM调用30秒超时
    "tool_call": 60,       # 工具调用60秒超时
    "total_request": 120,  # 单次请求120秒超时
    "agent_loop": 300,     # Agent循环300秒超时
}

FALLBACK_RESPONSE = "抱歉，处理超时。请稍后重试或联系人工客服。"

6. 数据与隐私（5项）

✅ 6.1 数据脱敏

检查：用户输入中的敏感信息（身份证号、银行卡号、手机号）是否脱敏后再发送给LLM？

✅ 6.2 数据驻留

检查：用户数据是否存储在合规的地理区域？是否满足GDPR/个保法要求？

✅ 6.3 对话数据保留策略

检查：对话记录的保留期限是否明确？过期数据是否自动删除？

✅ 6.4 训练数据选择退出

检查：发送给LLM提供商的数据是否声明了不用于训练？

# OpenAI: 设置不训练
headers = {
    "OpenAI-Organization": org_id,
}
# Azure OpenAI: 默认不训练
# Anthropic: 通过API设置

✅ 6.5 PII检测

检查：是否使用PII检测模型识别和过滤个人身份信息？

7. 质量保障（5项）

✅ 7.1 回归测试集

检查：是否有标准测试集定期运行，检测输出质量回归？

✅ 7.2 A/B测试

检查：新版本是否通过A/B测试验证效果后再全量发布？

✅ 7.3 人工审核

检查：高风险场景的输出是否经过人工审核？抽检比例是否合理？

✅ 7.4 幻觉检测

检查：是否对Agent输出进行幻觉检测？幻觉率是否监控？

✅ 7.5 边界测试

检查：是否测试了以下边界情况？

  • 空输入
  • 超长输入
  • 多语言混合
  • 特殊字符
  • 对抗性输入
  • 非相关领域问题

8. 可扩展性（4项）

✅ 8.1 水平扩展

检查：Agent服务是否支持水平扩展？是否是无状态的（或状态外部化）？

✅ 8.2 队列缓冲

检查：高峰期请求是否进入队列缓冲，避免服务过载？

✅ 8.3 资源隔离

检查：不同租户/用户的资源是否隔离？一个用户的高负载是否影响其他用户？

✅ 8.4 数据库扩展

检查：向量数据库、会话存储是否支持分片？能否支撑数据增长？

9. 用户体验（4项）

✅ 9.1 优雅降级

检查：服务不可用时是否有友好的降级体验？

GRACEFUL_DEGRADATION = {
    "llm_unavailable": "系统繁忙，已为您转接人工客服",
    "tool_unavailable": "该功能暂时不可用，请稍后再试",
    "rate_limited": "您的请求过于频繁，请稍后再试",
    "budget_exceeded": "今日使用额度已用完，请明天再试",
}

✅ 9.2 进度反馈

检查：长时间任务是否提供进度反馈？

✅ 9.3 多轮对话上下文

检查：多轮对话的上下文是否正确保持？用户引用之前内容时能否理解？

✅ 9.4 错误信息友好性

检查：错误信息是否对用户友好？是否暴露了技术细节？

10. 文档与运维（4项）

✅ 10.1 系统架构文档

检查：是否有最新的系统架构图、数据流图、Agent拓扑图？

✅ 10.2 运维Runbook

检查：是否有常见故障的应急处理手册？

## Runbook: LLM服务超时

### 症状
- 错误率飙升，错误类型为"llm_timeout"
- 用户反馈响应慢

### 处理步骤
1. 检查LLM服务商状态页
2. 如果是服务商问题，切换到备用模型
3. 如果是本地问题，检查网络连接
4. 必要时启用降级模式
5. 通知相关人员

✅ 10.3 变更管理

检查：Prompt修改、模型升级是否有变更管理流程？是否能快速回滚？

✅ 10.4 容量规划

检查：是否有容量规划文档？是否能预测未来3个月的资源需求？

快速自检表

将50项压缩为一页纸自检表：

安全：  [✅]输出过滤 [✅]输入消毒 [✅]工具权限 [✅]密钥管理 
        [✅]代码沙箱 [✅]速率限制 [✅]审计日志        7/7

性能：  [✅]延迟SLA [✅]流式响应 [✅]并行化 [✅]缓存 [✅]模型优化  5/5

成本：  [✅]Token预算 [✅]成本归因 [✅]模型路由 [✅]上下文压缩 [✅]成本告警  5/5

监控：  [✅]核心看板 [✅]追踪 [✅]错误分类 [✅]用户反馈 [✅]告警 [✅]在线评估  6/6

容错：  [✅]重试 [✅]降级 [✅]熔断 [✅]状态持久化 [✅]超时兜底  5/5

数据：  [✅]脱敏 [✅]数据驻留 [✅]保留策略 [✅]不训练 [✅]PII检测  5/5

质量：  [✅]回归测试 [✅]A/B测试 [✅]人工审核 [✅]幻觉检测 [✅]边界测试  5/5

扩展：  [✅]水平扩展 [✅]队列缓冲 [✅]资源隔离 [✅]数据库扩展  4/4

体验：  [✅]优雅降级 [✅]进度反馈 [✅]多轮上下文 [✅]友好错误  4/4

文档：  [✅]架构文档 [✅]Runbook [✅]变更管理 [✅]容量规划  4/4

总计： 50/50 ✅

结论

这50个检查项不是一次性的——它们应该是Agent系统的持续保障。建议：

  1. 上线前：必须100%通过所有🔴必须项
  2. 每月：审查所有指标，更新告警阈值
  3. 每季度：完整走一遍Checklist，确保没有遗漏
  4. 每次重大变更：重新评估相关检查项

生产部署不是终点，而是持续运营的起点。这份Checklist是你在Agent运营路上的安全网。

加入讨论

这篇文章有姊妹讨论帖在硅基AGI论坛 — 全球首个碳基硅基认知交流平台。

碳基与硅基的智慧碰撞，认知差异创造无限可能。