docs: 添加HTTP API文档和pricing_data使用指南
1. HTTP API接口文档：get_pricing_display.dspy 调用方式和返回示例 2. pricing_data两种格式说明：新格式(price_factors+unit_prices+unit)和旧格式(formula) 3. 完整示例：Token定价、视频生成定价、公式计算定价 4. 关键规则说明：unit_values、filters格式、value_mode等
This commit is contained in:
parent
c1bfaca049
commit
c2a7dbb98f
252
README.md
252
README.md
@ -331,6 +331,258 @@ llmage (模型管理) ──→ llm.ppid ──→ pricing_program.id
|
||||
|
||||
---
|
||||
|
||||
## HTTP API 接口
|
||||
|
||||
### 获取定价展示数据
|
||||
|
||||
```
|
||||
GET /pricing/api/get_pricing_display.dspy?ppid={ppid}
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**说明：** 返回指定定价项目的可读定价数据，供前端展示。自动解析 pricing_data 字段，转换为人类可读的价格表。
|
||||
|
||||
**返回示例（Token 定价）：**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"ppid": "5i1JIpqERgCWqKQ4DCegD",
|
||||
"name": "通义千问 qwen3.7-max",
|
||||
"pricing_type": "per_use",
|
||||
"items": [
|
||||
{
|
||||
"filters": {"model": "qwen3.7-max"},
|
||||
"filter_labels": {"模型": "qwen3.7-max"},
|
||||
"price_factors": [
|
||||
{
|
||||
"factor": "uncache_tokens",
|
||||
"label": "非缓存tokens",
|
||||
"unit_price": 6.0,
|
||||
"unit": "百万",
|
||||
"unit_label": "元/百万"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"filters": {"model": "qwen3.7-max"},
|
||||
"filter_labels": {"模型": "qwen3.7-max"},
|
||||
"price_factors": [
|
||||
{
|
||||
"factor": "cached_tokens",
|
||||
"label": "缓存tokens",
|
||||
"unit_price": 1.2,
|
||||
"unit": "百万",
|
||||
"unit_label": "元/百万"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"display_text": "【通义千问 qwen3.7-max】定价:\n - 非缓存tokens: 6.0 元/百万\n - 缓存tokens: 1.2 元/百万"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回示例（视频生成定价）：**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"ppid": "vidu_video_pricing",
|
||||
"name": "viduq3视频定价",
|
||||
"pricing_type": "per_use",
|
||||
"items": [
|
||||
{
|
||||
"filters": {"model": "viduq3-turbo", "resolution": "1080p", "off_peak": "0"},
|
||||
"filter_labels": {"模型": "viduq3-turbo", "分辨率": "1080p", "错峰": "0"},
|
||||
"price_factors": [
|
||||
{
|
||||
"factor": "duration",
|
||||
"label": "时长",
|
||||
"unit_price": 0.56,
|
||||
"unit": "秒",
|
||||
"unit_label": "元/秒"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"display_text": "【viduq3视频定价】定价:\n - 时长: 0.56 元/秒 [model=viduq3-turbo, resolution=1080p, off_peak=0]"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回字段说明：**
|
||||
|
||||
- `ppid`: 定价项目 ID
|
||||
- `name`: 定价项目名称
|
||||
- `pricing_type`: 定价类型（`per_use` 按次计费）
|
||||
- `items`: 定价项列表
|
||||
- `filters`: 过滤条件（如适用模型、分辨率等）
|
||||
- `filter_labels`: 过滤条件的中文标签
|
||||
- `price_factors`: 计价因子列表
|
||||
- `factor`: 因子字段名
|
||||
- `label`: 因子中文名称
|
||||
- `unit_price`: 单位价格（已转换为展示价，无需再乘）
|
||||
- `unit`: 单位（百万、秒、次等）
|
||||
- `unit_label`: 单位标签（元/百万、元/秒等）
|
||||
- `tiered`: 阶梯定价（仅当价格不同时展示）
|
||||
- `display_text`: 人类可读的价格表文本
|
||||
|
||||
---
|
||||
|
||||
## pricing_data 使用指南
|
||||
|
||||
### 两种格式
|
||||
|
||||
pricing_data 支持两种格式：
|
||||
|
||||
#### 1. 新格式（推荐）：price_factors + unit_prices + unit
|
||||
|
||||
适用于简单定价场景，直接指定计价因子和单位价格。
|
||||
|
||||
**示例 1：Token 定价（文本生成）**
|
||||
|
||||
```yaml
|
||||
unit_values:
|
||||
百万: 1000000
|
||||
fields:
|
||||
model:
|
||||
type: str
|
||||
role: filter
|
||||
label: 模型
|
||||
uncache_tokens:
|
||||
type: float
|
||||
role: factor
|
||||
label: 非缓存tokens
|
||||
cached_tokens:
|
||||
type: float
|
||||
role: factor
|
||||
label: 缓存tokens
|
||||
completion_tokens:
|
||||
type: float
|
||||
role: factor
|
||||
label: 输出tokens
|
||||
pricings:
|
||||
# 非缓存输入定价
|
||||
- price_factors: uncache_tokens
|
||||
unit_prices: 6.0
|
||||
unit: 百万
|
||||
filters:
|
||||
- model: qwen3.7-max
|
||||
|
||||
# 缓存输入定价
|
||||
- price_factors: cached_tokens
|
||||
unit_prices: 1.2
|
||||
unit: 百万
|
||||
filters:
|
||||
- model: qwen3.7-max
|
||||
|
||||
# 输出定价
|
||||
- price_factors: completion_tokens
|
||||
unit_prices: 18.0
|
||||
unit: 百万
|
||||
filters:
|
||||
- model: qwen3.7-max
|
||||
```
|
||||
|
||||
**示例 2：视频生成定价（多维度过滤）**
|
||||
|
||||
```yaml
|
||||
unit_values:
|
||||
次: 1
|
||||
fields:
|
||||
model:
|
||||
type: str
|
||||
role: filter
|
||||
label: 模型
|
||||
resolution:
|
||||
type: str
|
||||
role: filter
|
||||
label: 分辨率
|
||||
duration:
|
||||
type: int
|
||||
role: filter
|
||||
label: 时长(秒)
|
||||
value_mode: between
|
||||
off_peak:
|
||||
type: str
|
||||
role: filter
|
||||
label: 错峰执行
|
||||
flat:
|
||||
type: float
|
||||
role: factor
|
||||
label: 固定费用
|
||||
pricings:
|
||||
- price_factors: flat
|
||||
unit_prices: 85.0
|
||||
unit: 次
|
||||
filters:
|
||||
- model: viduq2-pro
|
||||
- resolution: 1080p
|
||||
- duration: '1'
|
||||
- off_peak: false
|
||||
|
||||
- price_factors: flat
|
||||
unit_prices: 43.0
|
||||
unit: 次
|
||||
filters:
|
||||
- model: viduq2-pro
|
||||
- resolution: 1080p
|
||||
- duration: '1'
|
||||
- off_peak: true
|
||||
|
||||
- price_factors: duration
|
||||
unit_prices: 0.56
|
||||
unit: 秒
|
||||
filters:
|
||||
- model: viduq3-turbo
|
||||
- resolution: 1080p
|
||||
- off_peak: 0
|
||||
```
|
||||
|
||||
#### 2. 旧格式：formula（公式计算）
|
||||
|
||||
适用于复杂定价场景，使用 Python 表达式计算金额。
|
||||
|
||||
**示例：按 Token 数量计算**
|
||||
|
||||
```yaml
|
||||
fields:
|
||||
model:
|
||||
type: str
|
||||
role: filter
|
||||
label: 模型
|
||||
prompt_tokens:
|
||||
type: float
|
||||
role: factor
|
||||
label: 输入tokens
|
||||
completion_tokens:
|
||||
type: float
|
||||
role: factor
|
||||
label: 输出tokens
|
||||
pricings:
|
||||
- model: gpt-4
|
||||
formula: (3.2 * prompt_tokens + 16 * completion_tokens) / 1000000.0
|
||||
|
||||
- model: gpt-3.5
|
||||
formula: (0.5 * prompt_tokens + 1.5 * completion_tokens) / 1000000.0
|
||||
```
|
||||
|
||||
### 关键规则
|
||||
|
||||
1. **unit_values 必须定义**：在 pricing_data 顶部定义 `unit_values`，如 `百万: 1000000`，用于单位换算
|
||||
2. **unit_prices 存储展示价**：新格式中 `unit_prices` 直接存储展示价格（如 `6.0` 表示 6.0 元/百万），不需要再乘以单位值
|
||||
3. **filters 支持两种格式**：
|
||||
- 列表格式：`filters: [{model: xxx}, {resolution: yyy}]`
|
||||
- 字典格式：直接作为字段写在 pricing 条目中
|
||||
4. **value_mode 默认精确匹配**：不指定时做 `=` 精确匹配，可指定 `between`、`in`、`>`、`<` 等
|
||||
5. **formula 可引用任意字段**：旧格式中 formula 可引用 config_data 中的任意字段名
|
||||
6. **多条件匹配**：如果多条定价规则都匹配，全部返回（不是只返回第一条）
|
||||
|
||||
---
|
||||
|
||||
## 关键设计要点
|
||||
|
||||
1. **YAML 驱动定价规则**：所有定价逻辑用 YAML 描述，支持字段定义、选项、匹配模式、计算公式
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user