mirror of
https://github.com/alibaba/higress.git
synced 2026-02-06 15:10:54 +08:00
139 lines
4.1 KiB
Markdown
139 lines
4.1 KiB
Markdown
# Agent Session Monitor - Quick Start
|
||
|
||
实时Agent对话观测程序，用于监控Higress访问日志，追踪多轮对话的token开销和模型使用情况。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 运行Demo
|
||
|
||
```bash
|
||
cd example
|
||
bash demo.sh
|
||
```
|
||
|
||
这将：
|
||
- 解析示例日志文件
|
||
- 列出所有session
|
||
- 显示session详细信息（包括完整的messages、question、answer、reasoning、tool_calls）
|
||
- 按模型和日期统计token开销
|
||
- 导出FinOps报表
|
||
|
||
### 2. 启动Web界面（推荐）
|
||
|
||
```bash
|
||
# 先解析日志生成session数据
|
||
python3 main.py --log-path /var/log/higress/access.log --output-dir ./sessions
|
||
|
||
# 启动Web服务器
|
||
python3 scripts/webserver.py --data-dir ./sessions --port 8888
|
||
|
||
# 浏览器访问
|
||
open http://localhost:8888
|
||
```
|
||
|
||
Web界面功能：
|
||
- 📊 总览所有session，按模型分组统计
|
||
- 🔍 点击session ID下钻查看完整对话
|
||
- 💬 查看每轮的messages、question、answer、reasoning、tool_calls
|
||
- 💰 实时计算token开销和成本
|
||
- 🔄 每30秒自动刷新
|
||
|
||
### 3. 在Clawdbot对话中使用
|
||
|
||
当用户询问当前会话token消耗时，生成观测链接：
|
||
|
||
```
|
||
你的当前会话ID: agent:main:discord:channel:1465367993012981988
|
||
|
||
查看详情：http://localhost:8888/session?id=agent:main:discord:channel:1465367993012981988
|
||
|
||
点击可以看到：
|
||
✅ 完整对话历史（每轮messages）
|
||
✅ Token消耗明细
|
||
✅ 工具调用记录
|
||
✅ 成本统计
|
||
```
|
||
|
||
### 4. 使用CLI查询（可选）
|
||
|
||
```bash
|
||
# 查看session详细信息
|
||
python3 scripts/cli.py show <session-id>
|
||
|
||
# 列出所有session
|
||
python3 scripts/cli.py list
|
||
|
||
# 按模型统计
|
||
python3 scripts/cli.py stats-model
|
||
|
||
# 导出报表
|
||
python3 scripts/cli.py export finops-report.json
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
✅ **完整对话追踪**：记录每轮对话的完整messages、question、answer、reasoning、tool_calls
|
||
✅ **Token开销统计**：区分input/output/reasoning/cached token，实时计算成本
|
||
✅ **Session聚合**：按session_id关联多轮对话
|
||
✅ **Web可视化界面**：浏览器访问，总览+下钻查看session详情
|
||
✅ **实时URL生成**：Clawdbot可根据当前会话ID生成观测链接
|
||
✅ **FinOps报表**：导出JSON/CSV格式的成本分析报告
|
||
|
||
## 日志格式要求
|
||
|
||
Higress访问日志需要包含ai_log字段（JSON格式），示例：
|
||
|
||
```json
|
||
{
|
||
"__file_offset__": "1000",
|
||
"timestamp": "2026-02-01T09:30:15Z",
|
||
"ai_log": "{\"session_id\":\"sess_abc\",\"messages\":[...],\"question\":\"...\",\"answer\":\"...\",\"input_token\":250,\"output_token\":160,\"model\":\"Qwen3-rerank\"}"
|
||
}
|
||
```
|
||
|
||
ai_log字段支持的属性：
|
||
- `session_id`: 会话标识（必需）
|
||
- `messages`: 完整对话历史
|
||
- `question`: 当前轮次问题
|
||
- `answer`: AI回答
|
||
- `reasoning`: 思考过程（DeepSeek等模型）
|
||
- `tool_calls`: 工具调用列表
|
||
- `input_token`: 输入token数
|
||
- `output_token`: 输出token数
|
||
- `model`: 模型名称
|
||
- `response_type`: 响应类型
|
||
|
||
## 输出目录结构
|
||
|
||
```
|
||
sessions/
|
||
├── agent:main:discord:1465367993012981988.json
|
||
└── agent:test:discord:9999999999999999999.json
|
||
```
|
||
|
||
每个session文件包含：
|
||
- 基本信息（创建时间、更新时间、模型）
|
||
- Token统计（总输入、总输出、总reasoning、总cached）
|
||
- 对话轮次列表（每轮的完整messages、question、answer、reasoning、tool_calls）
|
||
|
||
## 常见问题
|
||
|
||
**Q: 如何在Higress中配置session_id header？**
|
||
A: 在ai-statistics插件中配置`session_id_header`，或使用默认header（x-openclaw-session-key、x-clawdbot-session-key等）。详见PR #3420。
|
||
|
||
**Q: 支持哪些模型的pricing？**
|
||
A: 目前支持Qwen、DeepSeek、GPT-4、Claude等主流模型。可以在main.py的TOKEN_PRICING字典中添加新模型。
|
||
|
||
**Q: 如何实时监控日志文件变化？**
|
||
A: 直接运行main.py即可，程序使用定时轮询机制（每秒自动检查一次），无需安装额外依赖。
|
||
|
||
**Q: CLI查询速度慢？**
|
||
A: 大量session时，可以使用`--limit`限制结果数量，或按条件过滤（如`--sort-by cost`只查看成本最高的session）。
|
||
|
||
## 下一步
|
||
|
||
- 集成到Higress FinOps Dashboard
|
||
- 支持更多模型的pricing
|
||
- 添加趋势预测和异常检测
|
||
- 支持多数据源聚合分析
|