部署、观测与成本控制

学习目标

定义能帮助定位问题的运行日志。
在调用前检查预算，在调用后记录真实用量。
为上线准备配置、回滚和回归验证。

前置要求：Agent 循环和评估基础。本节代码只运行本地模拟调用，不会部署到云端或产生 API 费用。

从脚本到服务，需要补哪些边界

本地脚本通常由一个人运行，错误直接显示在终端。服务要同时处理不同用户、取消请求、保存状态，并在部分依赖失败时给出可理解结果。先把开发演示与真实服务的运行模式清楚标注。

关注点	本地实验	交付服务需要补齐
身份	手工指定用户	已验证会话与数据作用域
状态	内存字典	持久化、并发更新与迁移
调用	单次手动运行	超时、限流与预算
观察	print 输出	结构化日志与任务追踪
变更	直接改代码	版本记录、回归与回滚

不要一次性引入所有基础设施。先明确需要支持多少用户、哪些数据必须保存，以及允许多长响应时间。

每次运行记录什么

使用 run_id 关联同一任务的多个步骤，必要时增加父子调用 ID。记录版本、节点、开始时间、耗时、状态、错误码和用量。实际凭据、完整用户隐私和无关原文不应直接进入日志。

日志的目标是解释系统做了什么，不是收集所有内容。需要回查原文时，可保存受权限控制的引用，并设置保留期限。

一个离线预算与日志示例

保存为 observe.py 后运行。 simulated_cost_units 是人为设计的教学单位，不代表任何模型价格。

import json
import time
import uuid

def run(max_steps=3, budget_units=6):
    run_id = str(uuid.uuid4())
    spent = 0
    events = []
    for step in range(max_steps):
        reserved_cost = 3
        if spent + reserved_cost > budget_units:
            return {"status": "budget_exhausted", "spent_units": spent, "events": events}
        started = time.perf_counter()
        # 纯本地替身；真实调用需有服务端超时，并读取实际 usage。
        result = {"text": "模拟结果", "simulated_cost_units": 3}
        spent += result["simulated_cost_units"]
        events.append({
            "run_id": run_id,
            "app_version": "demo-v1",
            "step": step + 1,
            "node": "model_fixture",
            "status": "ok",
            "duration_ms": round((time.perf_counter() - started) * 1000, 3),
            "simulated_cost_units": result["simulated_cost_units"],
        })
    return {"status": "completed", "spent_units": spent, "events": events}

print(json.dumps(run(), ensure_ascii=False, indent=2))
print(json.dumps(run(max_steps=2), ensure_ascii=False, indent=2))

第一条运行尝试第三步之前发现预算不足，返回 budget_exhausted。第二条恰好完成两步，返回 completed。实际费用应使用提供商用量与当时价格计算，并记录价格版本。

预算预留不等于精确预测

模型输出长度事先不确定，可以用输入估计和输出上限计算保守预留。调用后按实际用量结算；多个并发请求需要原子地预留预算，避免同时超支。工具也可能有费用，不能只计算模型调用。

延迟需要分开看模型、工具、排队和应用处理。如果瓶颈是慢检索，只改提示词长度可能收效有限。对长任务提供真实阶段与取消入口，不要用固定动画假装进度。

一个可执行的上线顺序

冻结代码、提示词、模型配置与知识版本。
运行评估集，记录失败和允许上线的阈值。
配置服务端凭据、存储与资源限制。
在测试环境检查超时、断网、重启与恢复。
用少量真实任务观察，保留回到上一个版本的方法。

上线阈值由任务风险和使用场景决定，不存在适合所有 Agent 的统一准确率。部署平台的具体操作应遵循你选择的平台当前文档。本课程不要求为了学习先购买云资源。

练习与验收

给示例增加 tool_fixture 事件和独立预算。人为制造一次超时错误，记录稳定错误码并确认任务不会无限重试。

日志能按 run_id 还原步骤顺序。
预算检查发生在调用之前。
模拟费用与真实费用不会混淆。
运行说明写清环境变量、启动方式和回滚方法。

部署、观测与成本控制

学完这一课，你将能够