一、概述
DeepSeek API 用量分析仪表盘是一款纯浏览器端运行的数据可视化工具。您只需将 DeepSeek 平台导出的月度 CSV 账单文件拖拽到页面中，即可立即获得：
- 费用分析：总费用、每日费用趋势、各 API Key 费用占比
- 用量分析：总 Token 数、各 Key 用量明细、请求次数
- 缓存分析：缓存命中率、每日命中率趋势、各 Key 命中/未命中对比
- 趋势分析：在费用 / Token / 命中率 / 请求数四个维度间自由切换查看
- 社交媒体分享：每个标签页可生成信息图分享图片，一键复制到微信/飞书/钉钉
核心特点：所有数据解析和图表渲染均在您的浏览器本地完成，CSV 文件不会上传到任何服务器，保障您的账单数据隐私。
二、快速开始
2.1 从 DeepSeek 平台导出数据
- 登录 DeepSeek 平台
- 进入「用量（Usage）」页面
- 选择需要分析的月份，点击「导出（Export）」
- 每个月会下载一个 ZIP 压缩包，内含两个 CSV 文件：
amount-YYYY-M.csv— 用量明细文件（包含 Token 消耗、请求次数、缓存命中/未命中等数据）cost-YYYY-M.csv— 费用明细文件（包含按日的费用数据）
2.2 上传文件
- 打开仪表盘页面（默认为落地页状态）
- 将下载的 ZIP 压缩包直接拖拽到页面中央的上传区域（无需解压）
- 也可以拖拽解压后的 CSV 文件，或点击上传区域通过系统文件选择器选择文件
- 上传区域会显示「正在处理 CSV…」的加载状态
- 处理完成后，页面将自动切换到仪表盘视图
2.3 查看分析结果
上传完成后，页面会自动展示：
- 顶部 KPI 指标卡（总费用、总 Token 数、缓存命中率、活跃 API Key 数量）
- 通过下方标签页切换不同分析视图
- 如果有多个模型，可以使用模型筛选器单独查看某个模型的数据
三、导航栏使用说明
顶部导航栏固定在页面顶部，落地页和仪表盘页面共用。包含以下元素：
| 元素 | 说明 |
|---|---|
| Logo 图标 | 左侧显示仪表盘应用图标 |
| 应用名称 | 「DeepSeek API 用量分析」 |
| GitHub 图标 | 点击跳转到项目 GitHub 仓库 |
| 语言切换器 | Apple 风格胶囊分段控件，支持 EN / 中文 |
| 主题切换器 | 太阳/月亮图标按钮，切换浅色/深色主题 |
导航栏底部有一条细分割线，背景为页面主色调，始终浮动在最上层。
四、仪表盘界面说明
上传 CSV 文件成功解析后，页面自动从落地页切换到仪表盘视图。
4.1 操作栏
位于页面上方，包含两部分：
左侧 — 文件信息：
- 显示文件名标签（如
2026-5或2026-5 ~ 2026-6，多月份时显示范围） - 显示日期范围（如
2026-05-01 — 2026-05-31）
右侧 — 操作按钮：
- 加载其他文件：点击触发文件选择器，可加载新的 CSV 文件（替换当前数据）
- 清除（红色文字）：清空当前所有数据，返回落地页
4.2 错误与警告提示
错误横幅
当 CSV 解析出现严重错误时显示，包含：
- 错误类型标题（如「CSV 格式无法识别」「CSV 解析错误」「空文件」「上传不完整」）
- 错误详细描述
- 错误所在行号和列号（如有）
视觉样式：淡红色背景 + 红色边框 + 红色文字。
警告横幅
当数据存在非致命问题时显示，每条警告为独立横幅：
- 可能出现的警告类型：日期不匹配、缺少费用数据、缓存数据不完整、数据结构不一致
视觉样式：淡黄色背景 + 黄色边框 + 琥珀色文字。
4.3 KPI 指标卡
采用「无卡片」设计：4 列通栏大数字 + 细标签，底部以细横线分割。
| 指标 | 内容 |
|---|---|
| 总费用 | 格式化的货币金额，副行显示日期范围 |
| 总 Token 数 | 格式化的 Token 数量，副行显示模型数量 |
| 缓存命中率 | 百分比，副行显示由缓存节省的 Token 数 |
| 活跃 API Key | 数字，无副行 |
4.4 标签导航与模型筛选
标签导航
Apple 风格下划线标签，5 个标签页：
| 中文 | English |
|---|---|
| 总览 | Overview |
| 按自定义项目 | By Custom Projects |
| 按 Key | By Key |
| 缓存 | Cache |
| 趋势 | Trends |
- 选中标签：底部 2px 边框 + 主色文字
- 未选中标签：无底部边框 + 三级文字颜色
- 切换时有渐入动画
模型筛选器
当数据包含 2 个及以上模型时自动显示。Apple 风格胶囊分段控件：
- 全部模型：默认选中，显示所有模型合并数据
- 单个模型名：点击后仅显示该模型的数据
视觉：圆角胶囊组，选中项为深色填充 + 白色文字，未选中项透明白底 + 灰色文字。
4.5 总览视图
Hero 大数字
- 大数字：超大粗体总费用金额
- 标签：「总费用」
- 日期范围：数据覆盖的时间范围
每日费用柱状图
- 类型：ECharts 柱状图
- 内容：每日费用汇总，深色柱形，微圆角顶部
- 交互：支持悬停提示（显示具体日期和费用金额）
- x 轴超过 15 天时自动旋转日期标签
各 Key 费用环形图
- 类型：ECharts 环形图（donut）
- 内容：各 API Key 费用占比
- 图例：垂直排列在右侧
- 交互：悬停高亮显示标签
4.6 按 Key 视图
Hero 大数字
- 大数字：活跃 API Key 数量
- 标签：「活跃 API Key」
- 副行：Key 数量和模型数量
各 Key 详情表格
通栏表格，包含以下列：
| 列名 | 说明 |
|---|---|
| API Key 名称 | 主色加粗文字 |
| Token 数 | 次级色右对齐 |
| 费用 | 主色加粗右对齐 |
| 缓存命中 | 颜色编码：>40% 绿色、20-40% 琥珀色、<20% 红色 |
| 请求数 | 次级色右对齐 |
| 费用占比条 | 浅背景轨道 + 深色填充条，宽度按费用比例计算 |
表格行 hover 时有极淡的背景色变化。
4.7 缓存视图
有缓存数据时
Hero 大数字
- 大数字：缓存命中率百分比
- 标签：「缓存命中率」
- 副行：由缓存提供的 Token 数量
每日缓存命中率趋势图
- 类型：ECharts 折线图
- 内容：每日缓存命中率变化趋势（0-100%）
- 样式：绿色线条 + 极淡绿色半透明面积填充
各 Key 缓存命中/未命中堆叠柱状图
- 类型：ECharts 堆叠柱状图
- 内容：每个 Key 的缓存命中（绿色）和未命中（灰色）Token 数
- 图例：底部显示「缓存命中」「缓存未命中」
无缓存数据时
- 中央图标 + 「未检测到缓存使用」标题
- 「在 DeepSeek API 调用中启用提示缓存以降低费用。」提示文字
4.8 趋势视图
Hero 大数字（动态）
- 跟随当前选中的指标动态显示汇总值
- 格式按指标类型自动切换：费用 / Token / 缓存命中率 / 请求数
指标切换器
- 4 个纯文字标签：每日费用 / 每日 Token / 缓存命中率 / 请求次数
- 选中标签带底部下划线
- 切换时 Hero 大数字和图表同步更新
多指标折线图
- 类型：ECharts 折线图
- 内容：当前选中指标的每日趋势
- 样式：深色线条 + 极淡渐变面积填充
- 日期超过 30 天时启用内置缩放
4.9 按自定义项目视图
将 API Key 按自定义项目分组汇总分析，适合多项目团队按业务线查看用量。
Hero 数字
- 大数字：当前配置的项目总数量
- 标签：
个项目 - 副标题：
{n} 个 Key · {m} 个模型，与按 Key 视图风格一致
配置按钮
- 位置：
按项目标题行右侧 - 图标：齿轮图标 +
配置文字按钮 - 点击弹出配置浮窗
配置浮窗
- 项目列表：每个项目卡片包含：
- 项目名称输入框（可编辑）
- 已分配的 Key 小药丸（可拖拽、可点击 × 移除）
- 移除项目按钮（垃圾桶图标）
- 添加项目：虚线边框按钮，点击新增空白项目卡片
- 未分配 Key 区域：底部独立区域，显示所有未分配到任何项目的 Key
- 拖拽操作：
- 将 Key 从未分配区域拖拽到某个项目卡片 → 分配 Key 至该项目
- 将 Key 从项目卡片拖拽到未分配区域 → 移除 Key 的分配
- 将 Key 在不同项目之间拖拽 → 重新分配
- 拖入时目标区域高亮（accent 色边框 + 浅色背景）
- 保存 / 取消：保存时过滤空名称项目，写入浏览器本地存储
数据表格
布局与按 Key 视图一致：
| 列 | 说明 |
|---|---|
| Project | 项目名称（已配置项目为主色文字，未分类为三级文字） |
| Tokens | 完整 Token 数（逗号分隔，无缩写后缀） |
| Cost | 完整费用金额（¥ 符号 + 两位小数，可点击复制） |
| Cache Hit | 缓存命中率百分比（绿色 > 40%，琥珀色 20-40%，红色 < 20%） |
| Requests | 请求次数 |
| 占比条 | 费用横向占比条（未分类项半透明） |
- 未分类项：只在实际有数据时才显示，始终排在表格末尾
- 排序：按费用从高到低排列，未分类项始终在最后
项目配置保存在浏览器本地存储（localStorage），跨标签页自动同步。
五、全局功能说明
5.1 语言切换
位置：顶部导航栏右侧，Apple 风格胶囊分段控件。
- EN：切换到英文界面
- 中文：切换到中文界面
语言偏好自动保存到浏览器本地存储，下次访问时自动恢复。首次访问时根据浏览器语言自动检测。
5.2 主题切换（浅色/深色）
位置：顶部导航栏最右侧，圆形图标按钮。
- 浅色模式：冷灰纸质感背景，深色文字
- 深色模式：纯黑背景，浅色文字
主题偏好自动保存到浏览器本地存储，并优先跟随系统偏好。
5.3 多月份合并
支持同时上传多个月份的 ZIP 或 CSV 文件，合并规则如下：
- 如果上传的是 ZIP，系统首先解压提取其中的 CSV 文件
- 系统读取每个文件名，提取年份-月份键
- 将同名月份下的 amount 和 cost 文件自动配对
- 配对成功后，所有月份数据合并为一个连续的 CSV 文本进行解析
- 文件标签自动更新为范围格式
5.4 社交媒体分享
每个标签页均可生成一张 1200×630 的信息图分享图片，方便在微信、飞书、钉钉、Twitter 等社交平台传播。
使用步骤：
- 在任意标签页的导航栏右侧，点击 分享图标（节点连线图标）
- 在弹出窗口中填写：
- 你的名字 / 团队名字：显示为图片上大号 "From XXX" 署名（必填，自动记忆）
- 自定义文案：可选，以引文样式显示在卡片右上角（带示例占位文字）
- 下方预览区实时显示卡片效果
- 点击 「生成并复制」，图片自动复制到剪贴板，可直接粘贴到微信/飞书/钉钉
- 也可点击 「PNG」 按钮下载图片文件
卡片内容：
- 顶部：应用名称 + 当前标签页名称 + "From XXX" 署名 + 自定义文案（如有）
- 左侧：标签页核心指标（总览=总费用 / 项目=项目数 / Key=Key数 / 缓存=命中率 / 趋势=总费用）+ KPI 数值
- 右侧：对应标签页的迷你 ECharts 图表（柱状图/折线图/横向柱状图）
- 底部：数据日期范围 + 应用 Logo + 二维码（指向 deepseek-usage.xyz）+ 品牌水印
六、CSV 文件格式说明
amount CSV 格式
| 列名 | 说明 |
|---|---|
utc_date | UTC 日期 |
model | 模型名称 |
api_key_name | API Key 名称 |
api_key | API Key 值 |
type | 类型枚举 |
price | 单价（request_count 类型为空） |
amount | 数量 |
cost CSV 格式
| 列名 | 说明 |
|---|---|
utc_date | UTC 日期 |
model | 模型名称 |
cost | 费用（按日汇总） |
currency | 货币单位 |
注意事项
- 文件必须为 UTF-8 编码
- 列名必须完全匹配（大小写敏感）
- 可选列会被忽略，不会影响解析
七、隐私与安全说明
| 维度 | 说明 |
|---|---|
| 数据存储 | CSV 文件内容仅在浏览器内存中处理，不会写入磁盘或上传到任何服务器 |
| 网络请求 | 整个应用为静态站点，除初次加载页面资源外，不会发起任何数据上传请求 |
| 第三方依赖 | 所有依赖均在浏览器端运行，不通过外部 API 传输数据 |
| 开源透明 | 项目完全开源（GitHub），所有人都可以审查代码，验证隐私声明 |
八、常见问题排查
| 问题 | 可能原因 | 解决方法 |
|---|---|---|
| 上传后无反应 | 文件不是 CSV 或 ZIP 格式 | 确认文件后缀为 .csv 或 .zip，不要上传 Excel 或 PDF |
| 显示「文件过大」警告 | 单个文件超过 50 MB | 正常 DeepSeek 月度导出通常小于 1 MB；如果文件异常大，请检查是否误选了其他文件 |
| 显示 CSV 格式无法识别 | 列名不匹配或文件损坏 | 确认从 DeepSeek 官方平台导出，不要修改 ZIP 内的文件内容 |
| 费用数据显示为 0 | 缺少 cost CSV 文件 | 确保 ZIP 包含当月完整的 amount 和 cost，或单独上传缺失文件 |
| 上传 ZIP 无反应 | ZIP 内无 CSV 文件 | 确认 ZIP 包内包含 .csv 文件，不要上传仅有其他格式的压缩包 |
| 图表中某一天无数据 | 当天没有 API 调用 | 正常现象，不影响其他天数据 |
| 缓存视图显示未检测到缓存使用 | API 调用未启用 prompt caching | 在调用 DeepSeek API 时开启提示缓存功能 |
| 显示上传不完整 | 某个月份只有 amount 或只有 cost | 补充缺失的文件重新上传 |
| 多月份合并后数据异常 | 文件命名不规范 | 确保 ZIP 内文件名或直接上传的 CSV 文件名为标准格式 |
文档随应用版本迭代更新。如有疑问或建议，欢迎通过 GitHub Issues 反馈。