From 565c44d130765c425896007825b8ffbbbb01f10d Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Fri, 17 Jul 2026 17:23:58 +0800
Subject: [PATCH] docs: README with data sources, frequency, business logic,
 API docs

---
 README.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 123 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e470dc5..7827b3f 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,124 @@
-# sage_datamark
+# Sage DataMart — 数据集市模块
 
+模型性能监控、供应商性价比分析、多维度数据下钻。
+
+## 数据来源
+
+| 数据源 | 表 | 说明 |
+|--------|-----|------|
+| 模型调用记录 | `llmusage` | 每次 API 调用的详细日志 |
+| 模型定义 | `llm` | 模型名称、目录类型、供应商、owner |
+| 组织架构 | `organization` | 分销商→供应商→客户层级关系 |
+| 定价 | `pricing_program_timing` | 各模型供应商定价数据 |
+
+## 集市表
+
+| 表名 | 说明 | 粒度 |
+|------|------|------|
+| `dm_model_call_fact` | 模型调用事实表 | 每次调用 |
+| `dm_model_perf_daily` | 模型性能天汇总 | 天/模型/组织 |
+| `dm_provider_cost_daily` | 供应商性价比天汇总 | 天/模型/供应商 |
+
+## 取数频率
+
+| ETL 任务 | 频率 | 说明 |
+|----------|------|------|
+| `sync_call_fact` | 每 5 分钟 | 增量同步 llmusage → dm_model_call_fact |
+| `aggregate_daily_perf` | 每小时 | 聚合当天 dm_model_call_fact → dm_model_perf_daily |
+| `aggregate_provider_cost` | 每天 1 次 | 聚合同模型供应商性价比 → dm_provider_cost_daily |
+
+## 业务指标
+
+### 性能指标
+- **TTFT** (Time To First Token): 首 Token 响应时间，来源 `llmusage.responsed_seconds`
+- **TTOT** (Time To Output Total): 完成时间，来源 `llmusage.finish_seconds`
+- **成功率**: `status='SUCCEEDED'` / 总调用数
+- **失败率**: `status='FAILED'` / 总调用数
+- **并发度**: 同一时间窗口内活跃请求数
+
+### 性价比
+- **单价**: `total_amount / total_tokens`，按模型+供应商维度对比
+- **TTFT × 单价**：综合性价比排序
+
+### 多维度
+- **分销商(owner)** → **供应商(reseller)** → **销售(sale)** → **客户(customer)**
+- 每层独立统计：用量、模型分布、性能、费用
+
+## Dashboard 看板
+
+### 模型性能看板 `/sage_datamark/index.ui`
+- 4 个统计卡片：平均 TTFT、成功率、今日调用、失败数
+- 模型排行表：TTFT / TTOT / 成功率 / 调用次数 / 金额
+
+### 供应商性价比看板 `/sage_datamark/provider_roi.ui`
+- 同模型不同供应商对比
+- 单价(¥/token)、TTFT、调用次数、总费用
+
+## API 接口
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/sage_datamark/api/model_perf.dspy` | POST | 模型性能统计 |
+| `/sage_datamark/api/provider_roi.dspy` | POST | 供应商性价比 |
+
+### model_perf.dspy
+```json
+// 请求
+{"date": "2026-07-17", "model": "qwen3-max"}
+
+// 响应
+[{
+    "model": "qwen3-max",
+    "avg_ttft_ms": 320.5,
+    "avg_ttot_ms": 2100.3,
+    "success_rate": 98.5,
+    "total_calls": 12340,
+    "success_calls": 12155,
+    "fail_calls": 185,
+    "total_amount": 246.80
+}]
+```
+
+### provider_roi.dspy
+```json
+// 请求
+{"model": "qwen3-max"}
+
+// 响应
+[{
+    "model": "qwen3-max",
+    "providerid": "aliyun",
+    "total_calls": 5000,
+    "total_tokens": 5000000,
+    "total_amount": 10.00,
+    "unit_price": 0.000002,
+    "avg_ttft_ms": 280.5
+}]
+```
+
+## 部署
+
+```bash
+cd ~/sage/pkgs
+git clone git@git.opencomputing.cn:yumoqing/sage_datamark.git
+cd sage_datamark && pip install .
+py3/bin/python scripts/load_path.py
+
+# 添加 ETL cron 任务（在 Sage start.sh 或系统 cron）
+# 每 5 分钟同步
+*/5 * * * * cd ~/sage && py3/bin/python -c "
+from sage_datamark.etl import run_etl_sync
+from sqlor.dbpools import DBPools
+from appPublic.jsonConfig import getConfig
+import asyncio
+config = getConfig('.')
+db = DBPools(config.databases)
+async def go():
+    env_dbname = ServerEnv().get_module_dbname('sage_datamark')
+    async with db.sqlorContext(env_dbname) as sor:
+        await run_etl_sync(sor)
+asyncio.run(go())
+"
+
+# 重启 Sage，访问 /sage_datamark/index.ui
+```