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 描述，支持字段定义、选项、匹配模式、计算公式
|
1. **YAML 驱动定价规则**：所有定价逻辑用 YAML 描述，支持字段定义、选项、匹配模式、计算公式
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user