开源工具token-usage-ui：可视化监控LLM API Token用量与成本

1. 项目概述一个为AI开发者量身打造的Token用量监控利器如果你正在开发基于OpenAI、Anthropic、Azure OpenAI等主流大语言模型API的应用那么“Token用量”这个指标你一定不会陌生。它直接关联着你的API调用成本、应用性能甚至是用户体验。然而原生的API响应里Token信息往往只是几个冰冷的数字散落在日志的海洋中。当你想分析不同用户、不同功能、不同时间段的Token消耗模式或者想为不同团队或客户进行成本分摊时手动统计无异于一场噩梦。这正是我最初遇到的困境也是促使我深度使用并研究Walliiee/token-usage-ui这个开源项目的直接原因。简单来说token-usage-ui是一个轻量级、自托管的Web用户界面专门用于可视化、分析和监控来自多个LLM大语言模型供应商的API Token使用情况。它不是一个独立的日志系统而是一个强大的“仪表盘”需要你将自己的应用日志特别是包含Token消耗数据的日志导入到它支持的数据库中如SQLite、PostgreSQL然后它便能为你呈现清晰直观的图表和报告。你可以把它想象成你API成本数据的“专属财务总监”把杂乱的流水账整理成一目了然的财务报表。这个项目非常适合以下几类开发者一是独立开发者或小团队希望以最低成本监控自己产品的API开销二是企业内部正在试验或部署多个AI应用的团队需要进行跨项目的成本核算和优化三是为客户端提供AI集成服务的开发者需要向客户透明化地展示资源使用情况。它的核心价值在于将技术指标Token数直接转化为业务指标成本、效率让不可见的消耗变得可见、可分析、可管理。2. 核心设计思路从数据聚合到可视化洞察2.1 解决的核心痛点成本黑盒与优化无据在接触 token-usage-ui 之前我和团队监控Token用量的方式非常原始写脚本定期从云服务商的账单里拉取总费用或者从应用日志里用grep和awk勉强统计个总数。这种方式存在几个致命缺陷粒度太粗只能看到总花费不知道是哪个功能、哪个用户、哪个模型消耗了大头。当某个月账单突然飙升时排查起来如同大海捞针。实时性差云账单通常有数小时甚至一天的延迟无法及时预警异常消耗。缺乏关联性Token消耗无法与具体的请求参数如提示词长度、模型类型、用户行为或业务指标关联起来无法进行深度的“性价比”分析。分摊困难在多租户或为多个客户服务的场景下无法公平、准确地将API成本分摊到具体客户或项目上。token-usage-ui 的设计哲学正是直击这些痛点。它没有尝试重新发明轮子去收集日志而是采用了非常务实的“数据消费方”定位。它假设你已经有了结构化的日志数据或者你愿意花一点功夫将日志整理成结构化数据它的任务是高效地“消费”这些数据并提供强大的查询与展示能力。2.2 架构选型轻量、灵活与可扩展项目的技术栈选择体现了其“轻量级监控仪表盘”的定位。前端基于现代化的React框架搭配Recharts等图表库确保了交互体验的流畅与美观。后端通常是一个简单的Node.js或Python服务负责从数据库读取数据并通过API提供给前端。整个应用可以轻松地通过Docker容器化部署几乎可以在任何有Docker环境的地方运行包括你自己的笔记本电脑、开发服务器或云主机。这种架构带来的最大优势是“低侵入性”和“高灵活性”。低侵入性你不需要大规模改造现有应用的代码。只需要确保在调用LLM API后将必要的使用数据如timestamp,user_id,project,model,prompt_tokens,completion_tokens,total_tokens等写入到token-usage-ui支持的数据库中即可。这可以通过在应用代码中增加几行日志记录逻辑或通过像OpenTelemetry这样的可观测性框架来实现。高灵活性因为它与你的数据源数据库是解耦的所以你可以自由选择如何收集和存储数据。你可以用最简单的脚本将JSON日志文件解析后插入数据库也可以搭建一个复杂的日志管道。数据库方面它通常支持从轻量级的SQLite适合个人或小规模使用到更强大的PostgreSQL适合团队和生产环境。注意token-usage-ui 项目本身可能不包含一个开箱即用的、自动从你的应用抓取日志的“采集器”。你需要自己实现数据注入的部分。这是理解这个项目性质的关键——它提供的是“展示层”和“分析层”而“数据层”需要你根据自己的架构来适配。2.3 数据模型设计如何定义一次Token消耗要让这个系统工作我们需要一个清晰的数据模型。虽然具体表结构可能因版本而异但其核心思想是围绕“一次API调用事件”来记录。一个最小化的有效记录应该包含以下字段字段名类型描述必要性id自增主键记录唯一标识必需timestampDateTimeAPI调用发生的时间必需用于时间序列分析user_id/api_keyString调用者标识可以是内部用户ID、API Key别名或客户端ID强烈推荐用于按用户/客户分摊成本project/endpointString项目或功能模块名称如 “chat_service”, “summary_api”强烈推荐用于按业务维度分析modelString调用的LLM模型名称如 “gpt-4-turbo”, “claude-3-sonnet”必需不同模型单价不同prompt_tokensInteger提示词消耗的Token数必需completion_tokensInteger返回内容消耗的Token数必需total_tokensInteger总Token数通常为前两者之和推荐方便直接查询costDecimal (可选)估算的成本可根据model和total_tokens实时计算或事后填入可选但可视化时更直观有了这个基础模型你就能回答诸如“过去一周里用户‘Alice’在‘文档总结’功能上使用GPT-4花了多少钱”这类业务问题了。3. 部署与配置实操从零搭建你的监控面板3.1 环境准备与项目获取假设我们选择最经典的Docker部署方式这能最大程度避免环境依赖问题。首先确保你的服务器或本地机器已经安装了Docker和Docker Compose。获取项目代码通常有两种方式直接Clone仓库git clone https://github.com/walliiee/token-usage-ui.git使用Docker镜像如果作者提供了官方镜像如walliiee/token-usage-ui:latest部署会更简单。你需要查看项目的README来确认推荐方式。为了演示我们假设采用Clone代码并配合Docker Compose的方式这样更容易自定义配置如数据库连接。# 1. 克隆项目 git clone https://github.com/walliiee/token-usage-ui.git cd token-usage-ui # 2. 查看项目结构通常会有 docker-compose.yml 和 .env.example 文件 ls -la3.2 数据库配置与初始化token-usage-ui 本身不包含数据库你需要单独部署一个。这里以PostgreSQL为例因为它在生产环境中更可靠。我们在docker-compose.yml同级目录下创建一个.env文件来管理环境变量并编写一个docker-compose.yml文件。.env 文件内容示例# PostgreSQL 配置 POSTGRES_DBtoken_usage POSTGRES_USERadmin POSTGRES_PASSWORDyour_secure_password_here POSTGRES_HOSTdb # Docker Compose中的服务名 POSTGRES_PORT5432 # Token Usage UI 配置 (根据项目实际需要的环境变量调整此处为示例) UI_PORT3000 DATABASE_URLpostgresql://admin:your_secure_password_heredb:5432/token_usagedocker-compose.yml 文件内容示例version: 3.8 services: db: image: postgres:15-alpine container_name: token-usage-db restart: unless-stopped environment: POSTGRES_DB: ${POSTGRES_DB} POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - postgres_data:/var/lib/postgresql/data ports: - 5432:5432 # 主机端口映射方便本地工具连接 token-usage-ui: # 假设有官方镜像否则需要构建 image: walliiee/token-usage-ui:latest # 或使用 build: . container_name: token-usage-ui restart: unless-stopped depends_on: - db environment: DATABASE_URL: ${DATABASE_URL} UI_PORT: ${UI_PORT} ports: - ${UI_PORT}:${UI_PORT} volumes: # 如果需要挂载配置文件或静态资源可以在这里配置 - ./config:/app/config volumes: postgres_data:然后启动服务docker-compose up -d启动后数据库容器和UI容器应该都在运行。你可以通过docker ps检查状态并通过http://localhost:3000访问Web界面如果UI_PORT设为3000。实操心得在第一次启动后UI可能因为数据库表不存在而报错。很多这类项目会在首次启动时自动运行数据库迁移migration脚本。如果没有你通常需要在项目代码中找到schema.sql或类似的SQL文件手动连接到PostgreSQL容器执行它来创建表。连接命令如docker exec -it token-usage-db psql -U admin -d token_usage -f /path/to/schema.sql需要先将schema文件复制到容器内。务必在注入数据前完成这一步。3.3 数据注入连接你的应用到监控系统这是最关键的一步。你需要修改你的AI应用代码在每次成功调用LLM API后将使用数据插入到上述的PostgreSQL数据库中。以下是一个Python使用psycopg2库和OpenAI SDK的简单示例import psycopg2 from openai import OpenAI import os from datetime import datetime # 数据库连接配置应从环境变量读取 DB_CONFIG { host: os.getenv(DB_HOST, localhost), port: os.getenv(DB_PORT, 5432), database: os.getenv(DB_NAME, token_usage), user: os.getenv(DB_USER, admin), password: os.getenv(DB_PASSWORD, ) } # OpenAI客户端 client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) def call_openai_and_log(user_id, project, prompt, modelgpt-3.5-turbo): 调用OpenAI API并记录Token用量 try: response client.chat.completions.create( modelmodel, messages[{role: user, content: prompt}] ) # 提取用量信息 usage response.usage prompt_tokens usage.prompt_tokens completion_tokens usage.completion_tokens total_tokens usage.total_tokens # 插入数据库 conn psycopg2.connect(**DB_CONFIG) cursor conn.cursor() insert_query INSERT INTO api_usage (timestamp, user_id, project, model, prompt_tokens, completion_tokens, total_tokens) VALUES (%s, %s, %s, %s, %s, %s, %s) cursor.execute(insert_query, ( datetime.utcnow(), # 使用UTC时间保持一致性 user_id, project, model, prompt_tokens, completion_tokens, total_tokens )) conn.commit() cursor.close() conn.close() print(fAPI调用成功Token已记录。Prompt: {prompt_tokens}, Completion: {completion_tokens}) return response.choices[0].message.content except Exception as e: print(f调用或记录失败: {e}) # 在实际生产中这里应该有更完善的错误处理和重试逻辑 return None # 示例调用 # result call_openai_and_log(user_iduser_123, projectcustomer_support, promptHello, how are you?)注意事项性能考虑同步插入数据库可能会增加API调用的延迟。对于高性能场景建议采用异步方式例如将日志事件发送到一个消息队列如Redis Streams、RabbitMQ然后由另一个消费者服务批量写入数据库。错误处理数据库插入失败不应导致主业务逻辑失败。务必做好异常捕获也许可以降级为写入本地文件稍后补录。数据安全确保数据库连接信息密码等通过环境变量管理不要硬编码在代码中。4. 功能深度解析与使用技巧4.1 核心仪表盘一眼看清全局与趋势成功部署并注入数据后登录token-usage-ui你首先看到的应该是一个综合仪表盘。一个设计良好的仪表盘通常会包含以下核心部件关键指标卡片展示“今日总Token消耗”、“本月总成本”、“活跃用户数”、“最常用模型”等实时汇总数据。这让你对当前状态有一个瞬时把握。时间序列折线图这是最重要的图表之一。它展示了Token消耗量或估算成本随时间如按小时、按天的变化趋势。你可以通过它快速发现异常峰值例如某个深夜突然出现的高消耗可能意味着有异常脚本在运行或遭到攻击。消耗分布环形图或堆叠柱状图按模型分布直观显示GPT-4、Claude-3、GPT-3.5-Turbo等不同模型各自消耗的Token占比。这直接关系到你的成本结构如果发现昂贵的GPT-4被大量用于简单任务就是优化的信号。按项目/功能分布显示“智能客服”、“代码生成”、“内容润色”等不同业务模块的消耗情况。帮助你识别哪些功能是“成本大户”评估其投入产出比。按用户/客户分布在多租户场景下此图表是成本分摊的核心依据。它能清晰指出高消耗用户便于后续的套餐设计或资源沟通。使用技巧充分利用时间筛选器。对比“本周”与“上周”的数据可以观察业务增长趋势聚焦“过去24小时”可以用于实时监控和故障排查。很多问题如提示词工程失误导致循环调用在时间序列图上会暴露无遗。4.2 高级筛选与下钻分析定位问题根源仪表盘提供了宏观视角而高级筛选和下钻功能则是你进行微观调查的“显微镜”。一个合格的token-usage-ui应该支持多维度组合筛选例如时间范围特定用户特定模型项目AToken消耗大于1000的请求通过这样的筛选你可以精准地回答诸如“客户B在过去一个月里在代码审查功能上使用GPT-4花了多少钱”这类具体问题。下钻分析通常指在图表上点击某个数据点例如环形图中“GPT-4”的区块系统会自动筛选出所有使用GPT-4的记录并展示其详情列表。你可以进一步查看每一条请求的具体时间、用户、消耗的Token数甚至如果日志记录了请求ID你还能回溯到原始的应用日志查看当时的完整提示词和回复这对于调试和优化提示词工程至关重要。4.3 成本估算与报告导出从数据到决策Token数本身是技术指标乘以单价才是成本。一个进阶功能是成本估算。系统可以内置或允许你配置各模型的单价如GPT-4输入$0.03/1K tokens输出$0.06/1K tokens。配置好后所有图表和报表都可以直接以货币单位如美元展示这对非技术背景的决策者如产品经理、财务更加友好。报告导出功能允许你将筛选后的数据以CSV或PDF格式导出。这对于定期生成周报、月报或为客户生成用量账单非常有用。你可以设置一个定时任务每周一自动生成上周的用量报告并发送到团队邮箱。实操心得在配置模型单价时务必注意区分“输入Token”和“输出Token”的价格以及不同上下文长度如8K、32K、128K模型的价差。如果系统不支持自动区分你可能需要在记录数据时就将估算成本计算好并存入cost字段。另外注意价格可能随时变动最好建立一个定期检查和更新单价配置的机制。5. 生产环境进阶考量与优化5.1 性能与数据量管理随着时间推移api_usage表的数据会快速增长。如果每天有数万次调用几个月后数据量就会非常庞大可能影响查询和仪表盘的加载速度。索引策略务必为常用的查询字段建立数据库索引这能极大提升查询效率。至少应该为timestamp时间范围查询、user_id按用户筛选、project按项目筛选、model按模型筛选这几个字段创建索引。-- 示例PostgreSQL索引创建语句 CREATE INDEX idx_usage_timestamp ON api_usage (timestamp); CREATE INDEX idx_usage_user_project ON api_usage (user_id, project);数据分区/归档对于时间序列数据按时间如按月进行表分区是标准做法。旧数据如三个月前的查询频率低可以将其迁移到归档表或更便宜的存储中主表只保留热数据。一些监控系统会自带数据滚动清理retention策略。聚合表对于仪表盘上展示的日汇总、月汇总数据可以提前计算好并存入另一张聚合表。这样在查询“本月总消耗”时就不需要去扫描数千万条的明细记录而是直接查询只有几十条记录的聚合表性能提升立竿见影。5.2 数据采集架构优化如前所述直接在业务代码中同步写数据库并非最佳实践。一个更健壮的架构是[你的AI应用] -- (发送日志事件) -- [消息队列如Redis/RabbitMQ/Kafka] -- [日志消费服务] -- (批量写入) -- [监控数据库] | v [实时监控/报警]消息队列解耦业务逻辑和数据记录逻辑即使监控数据库暂时不可用也不会影响核心业务。日志消费服务一个独立的后台服务从消息队列中消费日志可以进行批量插入、数据清洗、格式转换甚至实时计算初步聚合指标。实时报警消费服务可以同时将异常数据如单次请求Token数超过1万、某一用户短时间内请求频率异常发送到报警系统如钉钉、Slack、PagerDuty实现主动预警。5.3 安全与权限控制在生产环境中监控数据可能包含敏感信息如内部用户ID、项目名称、资源消耗模式。界面访问控制token-usage-ui 的Web界面必须设置登录认证。简单的可以通过HTTP Basic Auth或者集成到你现有的单点登录SSO系统中。绝对不要将其不加保护地暴露在公网上。数据权限隔离如果你的系统需要支持多团队或多客户查看且数据需要隔离那么简单的单数据库单表就不够了。你可能需要在数据记录时增加一个tenant_id租户ID字段。修改token-usage-ui使其在查询时强制带上当前登录用户所属租户的过滤条件。这通常需要修改后端API的查询逻辑。或者为每个租户部署独立的数据库实例但这会大大增加运维复杂度。更常见的做法是在应用层通过tenant_id进行逻辑隔离。6. 常见问题排查与实战经验在实际部署和使用 token-usage-ui 或其类似自建系统的过程中我遇到过不少典型问题这里总结一下希望能帮你避坑。问题1仪表盘图表不显示数据或显示异常。排查步骤检查数据注入首先确认你的应用是否成功将数据写入数据库。直接连上数据库执行SELECT COUNT(*) FROM api_usage;和SELECT * FROM api_usage ORDER BY timestamp DESC LIMIT 5;看看是否有近期数据字段值是否正确。检查时间筛选器这是最常见的原因。确认仪表盘左上角的时间范围筛选器是否设置正确是否覆盖了你数据的时间段。尝试选择“所有时间”看看。检查前端控制台打开浏览器的开发者工具F12切换到“网络(Network)”标签刷新页面查看加载图表数据的API请求通常是/api/usage/stats之类的。看看请求是否成功状态码200以及返回的JSON数据是否为空或格式错误。检查后端日志查看 token-usage-ui 后端容器的日志docker logs token-usage-ui看是否有数据库连接错误或查询SQL语法错误。问题2查询速度非常慢尤其是选择长时间范围时。原因与解决缺乏索引如上文所述为关键查询字段添加索引是首要任务。数据量过大考虑实施数据分区和归档策略。对于历史数据的查询可以引导用户使用导出的聚合报告而非在交互式仪表盘上查询全量明细。聚合查询复杂检查后端是否在每次请求时都进行复杂的实时聚合计算。对于固定的聚合视图如日报表可以改为定时任务预计算。问题3估算的成本与实际云账单有出入。原因分析价格未及时更新LLM API价格特别是促销价或谈判价可能与你配置的默认单价不同。确保你配置的单价准确。未计入其他费用你的监控可能只记录了主要文本模型的Token费用但云账单可能还包括了图片生成DALL-E费用、语音合成TTS费用、文件处理费用、以及额外的网络流量或API请求次数费用。数据丢失或重复在数据采集、传输过程中可能存在少量记录丢失或重复导致统计偏差。建议定期如每周将系统统计的总Token数与云服务商控制台提供的用量统计进行对账。问题4如何监控非OpenAI的模型token-usage-ui 的核心是数据模型它不关心数据来自哪里。只要你能从 Anthropic Claude、Google Gemini、Azure OpenAI、甚至是本地部署的 Llama 等模型的API响应中提取出prompt_tokens和completion_tokens或等效信息并以相同的格式写入数据库它就能进行统一监控。你甚至可以为不同供应商的模型定义统一的model字段命名规范如claude-3-opus-20240229、gemini-1.5-pro。一个重要的实战经验从第一天就开始记录。不要等到成本失控时才想起来要监控。在项目初期即使数据量很小建立这套监控流程也能帮助你养成关注成本的习惯并为后续的容量规划、定价策略提供宝贵的历史数据基线。你可以从一个简单的SQLite数据库和最基本的每日总消耗图表开始随着业务复杂度的提升再逐步演进到更完整的架构。