计费规则
积分制计费 · 按量付费 · 失败零扣费 · 5 分钟缓存低价 · 统一账单
药图智能开放平台采用积分(credits)计费模式。API、Skill、MCP 三种接入方式共用同一套积分,统一账单、统一管理。每个端点按调用消耗固定积分,失败请求完全不计费,相同参数 5 分钟内重复请求命中缓存仅扣 1 积分。
各端点积分消耗
| 端点 | 说明 | 积分消耗 |
|---|---|---|
| /search | 提交直接关系(1-hop)搜索 | 11 |
| /search-indirect | 提交多跳路径搜索 | 11 |
| /resolve | 实体名解析(别名/缩写 → 图谱 ID) | 11 |
| /status | 轮询异步搜索任务的执行状态 | 1 |
| /details | 分页获取直接关系搜索的完整结果(支持 result_id 复用) | 1 + 返回关系条目数 |
| /details-indirect | 分页获取多跳路径搜索的完整路径详情 | 1 + 路径总跳数之和 |
| /evidences | 获取指定关系的文献证据列表 | 1 + 页内证据条数 × 10 |
| /evidences-indirect | 获取多跳路径中每一跳的文献证据 | 1 + 页内证据条数 × 10 |
总体原则:按调用复杂度从平台账户扣减 credits。
缓存机制
为降低重复查询成本,系统提供两层缓存:
- 平台 5 分钟响应缓存(per user):同一用户 5 分钟内完全相同的请求体(包括 page、page_size、空格),返回上次响应体,仅扣 1 积分
- 上游搜索缓存:保留期更长,按搜索参数 hash 跨用户共享;命中时仍走完整流程(task_id → 首次 poll 即 completed)
- 想强制刷新:改任意字段,或在搜索请求体加 enforce_refetch="1"
- 搜索任务结果(result_id)永久有效,可复用避免重复搜索
失败零扣费承诺
所有失败请求完全不消耗积分,你可以放心调试:
- 平台层:鉴权失败、额度不足、参数错误 → 直接拒绝,完全不扣
- 上游返回 4xx / 5xx → 平台完全不扣,记一条 consumption=0 的失败日志
- 搜索任务执行失败(status=failed)
承诺:只有成功返回结果的请求才消耗积分。调试阶段也无需担心意外扣费。
响应中的计费用字段
每个成功响应会带平台口径的积分字段,可用于客户端成本核算:
{
"platform_credits_consumed": 16,
"platform_credits_remaining": 999850,
...
}
消费记录(consumption_records)
登录后可在「使用统计 → 消费明细」逐笔查看,字段如下:
| 字段 | 说明 |
|---|---|
| 时间 | 请求发生时间 |
| request_type | 端点标签(search_direct / details_direct / evidences_direct / status / resolve / ...) |
| skill_name | 接入来源(药图智能 · 生物医学知识图谱 / iSearch · 文献专利检索) |
| consumption | 本次扣减的 credits 数(失败请求记 0) |
| 状态 | 成功 / 失败(失败完全不计费) |
成本控制建议
善用 result_id 复用结果
搜索结果的 result_id 永久有效。多次查看同一结果时,用 result_id 调 /details(1+条目数 credits)比重新 /search(11 credits)更经济。拿到 result_id 请立刻持久化。
利用 5 分钟缓存窗口
探索性参数调试时尽量保持请求体稳定,5 分钟内完全相同的请求体重复请求仅扣 1 积分(包括 page、page_size、空格都需完全一致)。
合理控制返回量
/details 用 requested_relations_count 限定条数——前 10 条按概率排已经够用;/evidences 先看 details 给的 evidence_count,按需拉取(每 page 默认 20 条,约 200+ credits 一页)。
多跳路径先用小 limit 试探
多跳搜索 limit 默认 100 路径,每路径 2-3 跳,details 至少 200~300 credits 起步。先用小 limit 试探再放量。
先解析,再搜索
实体名拼写错误会导致搜索无结果(虽然不计费,但浪费时间)。建议先调 /resolve 确认标准实体名,再进行正式搜索,提高命中率。