1. 项目概述一个被“放弃”的开源宝藏最近在整理自己的AI应用项目时发现OpenAI的API账单有点“失控”了。月初设定的预算到了月中就频频告警仔细一看全是各种调试、测试请求产生的费用真正有价值的调用成本反而被淹没在海量日志里。更头疼的是想优化一下提示词Prompt看看哪些请求效果不好、哪些模型调用最费钱却发现OpenAI官方后台提供的数据非常有限基本就是个“黑盒”。就在我四处寻找解决方案时在GitHub上发现了llm.report这个项目。它的Slogan直击痛点“一个为OpenAI打造的开源日志与分析平台”。简单来说它能帮你自动记录每一次API调用然后以清晰的可视化方式展示花费、分析用量、追踪用户成本甚至帮你优化提示词。这不正是我需要的“AI应用运维仪表盘”吗然而点进仓库第一眼看到的却是一个醒目的警告项目已不再积极维护创始人因未能找到可持续的商业模式而转向了其他项目。对于一个技术人来说这种“开源即弃坑”的情况并不少见但往往也意味着你捡到了一个功能完整、设计精良却无人问津的“宝藏”。llm.report就属于这一类。它的代码结构清晰技术栈现代Next.js, TypeScript, Tailwind CSS功能完全可用。对于中小团队或个人开发者自部署一个这样的内部监控平台成本极低收益却非常直观——你能立刻看清楚你的AI应用每一分钱花在了哪里。所以这篇文章不是介绍一个活跃项目而是分享如何将一个“静默”但成熟的开源项目转化为你自己技术栈中一个强有力的Ops运维工具。我会带你从零开始完成llm.report的本地部署、核心功能解析、数据对接并分享如何基于其代码进行定制化改造让它真正为你所用。如果你也在用OpenAI API开发应用并且对成本和效果优化感到头疼那这个“旧”项目或许能给你带来“新”的启发。2. 核心功能与价值解析不止是看账单llm.report的核心价值在于它将OpenAI API的“黑盒调用”变成了“白盒监控”。这不仅仅是事后查账单而是贯穿开发、测试、运营全流程的洞察工具。我们来拆解它的三大核心模块看看每一个部分具体解决了什么问题。2.1 OpenAI API 成本与用量分析这是最直接、最实用的功能。我们调用OpenAI的API时费用由使用的模型如gpt-3.5-turbo, gpt-4和消耗的令牌数Tokens决定。手动计算非常繁琐而llm.report会自动帮你完成这一切。它能回答的关键问题“我这个月到底花了多少钱”仪表盘会以日/周/月的维度展示总成本曲线一目了然。“钱都花在哪个模型上了”提供饼图或柱状图清晰显示gpt-3.5-turbo、gpt-4、text-embedding-ada-002等不同模型的成本占比。这能帮你决策是否过度依赖了昂贵的gpt-4某些场景能否用更便宜的3.5模型替代“每天的令牌消耗趋势如何”监控输入令牌Prompt Tokens和输出令牌Completion Tokens的每日用量。如果某天输出令牌激增可能意味着有提示词设计不当导致模型“废话”过多徒增成本。“每个请求的平均成本是多少”这个指标有助于评估你应用的整体经济性。结合用户行为分析可以计算单用户平均成本ARPU对商业化应用至关重要。实操心得很多开发者只关注总成本却忽略了“单位成本”。通过llm.report我发现自己早期有些提示词写得过于冗长包含了很多不必要的上下文导致输入令牌虚高。优化后在保持效果的前提下单次请求成本下降了约15%。这个分析面板是进行“成本优化”的起点。2.2 请求/响应日志与提示词工程这是面向开发者和AI工程师的深度功能。它记录每一次API调用的原始数据包括请求体完整的消息列表角色、内容、模型参数temperature, max_tokens等。响应体模型返回的消息、使用的令牌数、finish_reason停止原因。元数据请求时间、耗时、用户ID如果配置了、成本。这个日志系统的价值在于调试与排错当某个用户反馈AI回答“胡言乱语”时你可以直接根据时间或用户ID检索到当时的完整对话历史和参数精准复现问题而不是靠猜测。提示词迭代优化这是核心中的核心。你可以筛选出“高成本”或“高耗时”的请求具体分析它们的提示词设计。例如你会发现某些问题的提示词过于开放导致模型生成了非常长的、包含冗余信息的回答。你可以直接在这些日志的基础上修改提示词进行A/B测试。模型效果评估你可以对比同一个问题在不同模型如gpt-3.5-turbo vs gpt-4或不同参数下的回答质量与成本为不同场景选择最佳模型提供数据支撑。注意事项日志会包含所有对话内容这可能涉及用户隐私。在自部署时务必确保你的数据库安全并考虑是否需要匿名化或加密存储敏感信息。llm.report本身提供了基础的认证但数据安全策略需要根据你的业务要求自行加固。2.3 用户级成本分析如果你的应用面向多用户比如一个SaaS产品这个功能就是“黄金功能”。它能将API调用成本关联到具体的终端用户。实现原理是你在发送API请求时需要在请求的元数据中附带一个代表用户的唯一标识符如用户ID、Session ID。llm.report的后台会聚合这些数据从而计算出单个用户的总使用成本。单个用户的平均每次请求成本。用户群体的成本分布哪些是“高价值”用户哪些是“高成本”用户。这个数据的商业价值极大定价策略验证你的订阅费是否覆盖了典型用户的API成本如果大部分用户的使用成本都接近或超过你的订阅费那商业模式就有问题。识别异常用户快速定位到那些滥用API、产生异常高成本的用户可能是恶意爬虫或提示词注入攻击便于及时采取限制措施。精细化运营针对高活跃度、高成本用户提供更优质的服务或推荐更高级的套餐。踩坑记录初期集成时我忘记在SDK中设置用户ID导致所有成本都归为“匿名用户”这个功能就废了。务必在应用初始化阶段就规划好用户标识的传递逻辑。llm.report的SDK后面会讲提供了相应的方法集成起来并不复杂。3. 从零开始自部署llm.report全流程虽然项目不再维护但它的自托管安装脚本依然有效。下面我带你在本地或自己的服务器上完整跑起来。这里假设你使用Linux/macOS环境并已安装Docker和Docker Compose。3.1 环境准备与项目初始化首先把代码拉到本地。因为项目归档了这相当于拿到了一个“稳定版”。# 1. 克隆仓库 git clone https://github.com/dillionverma/llm.report.git cd llm.report # 2. 安装项目依赖 (使用yarn或npm) yarn install # 或 npm install接下来是配置环境变量。这是最关键的一步所有核心配置都在这里。# 3. 复制环境变量模板文件 cp .env.example .env现在用文本编辑器打开新创建的.env文件。你需要配置以下几个核心项# 数据库连接 (使用Docker Compose启动的本地库通常不用改) DATABASE_URLpostgresql://postgres:postgreslocalhost:5432/llmreport?schemapublic # NextAuth.js 的密钥用于会话加密。必须生成一个强密钥。 # 在终端运行openssl rand -base64 32将输出结果粘贴到这里。 NEXTAUTH_SECRET你的64位随机字符串 NEXTAUTH_URLhttp://localhost:3000 # 本地开发地址 # OpenAI API 密钥用于在llm.report后台测试功能非必需 OPENAI_API_KEYsk-... # 可选Resend邮件服务和 Stripe支付的密钥如果你需要用户注册、付费功能。 # 对于纯内部监控可以先不配置。 RESEND_API_KEY STRIPE_SECRET_KEY重要提示NEXTAUTH_SECRET务必使用openssl rand -base64 32命令生成这是保障你自部署应用安全的基础。不要使用简单的字符串。3.2 一键启动与初次登录llm.report非常贴心地提供了Docker Compose的一键启动脚本它会自动拉起PostgreSQL数据库并初始化表结构。# 4. 使用开发脚本快速启动依赖Docker yarn dx # 或 npm run dx这个命令会在后台启动数据库和Next.js应用。控制台输出中请务必留意最后几行它会打印出系统自动创建的初始管理员用户的登录邮箱和密码。格式通常类似Created test user: adminllm.report / password: xxxxxxxx打开浏览器访问http://localhost:3000。使用上面提供的邮箱和密码登录你就进入了llm.report的管理后台。常见问题排查端口冲突如果3000端口被占用可以在package.json或docker-compose.yml中修改Next.js的映射端口。数据库连接失败确保Docker服务正在运行。可以尝试docker ps查看Postgres容器是否正常启动。yarn dx 报错可能是依赖问题。尝试删除node_modules和yarn.lock重新执行yarn install。3.3 核心配置连接你的应用与llm.report空荡荡的后台是没有数据的。接下来我们要让你的AI应用把API调用日志发送到llm.report。项目提供了两种主要方式使用官方SDK或配置OpenAI官方代理。方案一使用llm.report的Node.js SDK推荐这种方式侵入性小最灵活。你需要在你的后端服务中安装SDK。# 在你的应用项目中安装SDK npm install llm-report # 或 yarn add llm-report然后在你的服务初始化代码中比如Express的app.js或Next.js的API全局拦截器引入并配置SDKconst { LLMReport } require(llm-report); const llmreport new LLMReport({ apiKey: YOUR_LLM_REPORT_API_KEY, // 在llm.report后台的Settings中生成 endpoint: http://localhost:3000/api/log, // 你的llm.report部署地址 }); // 示例在调用OpenAI API后手动记录日志 async function callOpenAI(prompt, userId) { const startTime Date.now(); const response await openai.chat.completions.create({ model: gpt-3.5-turbo, messages: [{ role: user, content: prompt }], }); const endTime Date.now(); // 关键将日志发送到llm.report await llmreport.log({ provider: openai, type: chat, model: response.model, prompt: prompt, response: response.choices[0].message.content, tokens: response.usage.total_tokens, user: userId, // 关联用户ID requestTime: startTime, responseTime: endTime, // ... 其他元数据 }); return response; }方案二配置OpenAI API Base URL零代码修改这是最巧妙的方式。llm.report可以充当一个“代理服务器”。你只需要修改你代码中OpenAI客户端的baseURL将其指向llm.report提供的代理端点所有请求会自动被记录。首先在llm.report后台的Settings中找到你的“API Key”和“Proxy Endpoint”例如http://your-llm-report-domain.com/api/proxy。然后修改你的OpenAI客户端初始化代码import OpenAI from openai; // 将baseURL指向llm.report的代理地址 const openai new OpenAI({ apiKey: your-openai-api-key, // 这里还是用你自己的OpenAI密钥 baseURL: http://localhost:3000/api/proxy, // 替换为你的llm.report代理地址 defaultHeaders: { X-LLM-Report-API-Key: YOUR_LLM_REPORT_API_KEY // 添加认证头 } }); // 之后所有通过这个client发起的调用都会被自动记录 const completion await openai.chat.completions.create({ model: gpt-3.5-turbo, messages: [{ role: user, content: Hello world }], });实操心得对于新项目我强烈推荐方案二。它几乎无需改动业务逻辑只需修改配置即可实现全量日志收集。对于已有项目如果修改全局客户端配置有困难可以采用方案一在关键的几个调用处手动埋点。SDK的log方法也允许你记录非OpenAI的模型调用如Azure OpenAI、Anthropic Claude扩展性更好。4. 深入定制与二次开发指南既然项目不再维护我们把它部署起来后很可能需要根据自己的业务进行定制。好在它的代码结构非常清晰基于现代Web技术栈修改起来并不困难。4.1 技术栈梳理与代码结构llm.report是一个标准的Next.js全栈应用这对React生态的开发者非常友好。前端框架Next.js 13 (App Router)使用TypeScript和Tailwind CSS。UI组件主要基于shadcn/ui这是一个可以自由复制代码的高质量组件库意味着你可以随意修改样式。后端Next.js API Routes。数据处理和业务逻辑主要在app/api/目录下。数据库PostgreSQL使用Prisma作为ORM。数据模型定义在prisma/schema.prisma中。认证NextAuth.js支持多种登录方式。核心日志逻辑位于lib/llmreport目录这是SDK和服务端日志处理的核心。如果你想增加一个新的数据分析维度比如按“对话会话”分组统计成本通常需要修改三个地方数据库模型schema.prisma可能需要新增字段或关系。API接口app/api/创建新的端点来接收和存储数据。前端页面app/dashboard/新增一个图表组件来展示数据。4.2 常见定制化场景与修改示例场景一增加对Azure OpenAI的支持llm.report默认主要对接OpenAI官方API。如果你的应用使用Azure OpenAI需要扩展其日志模型。修改Prisma模型在Log表中增加provider字段的枚举值或增加azure_deployment、azure_endpoint等字段。修改日志接收API如app/api/log/route.ts解析来自Azure OpenAI SDK的请求格式将额外信息存入数据库。在前端仪表盘中可以增加一个筛选器让用户按“提供商OpenAI/Azure”查看数据。场景二自定义成本计算规则OpenAI的定价模型可能会变或者你使用了通过其他渠道获得的模型其定价不同。你可以修改成本计算逻辑。成本计算的核心函数通常在lib/cost-calculation.ts或类似文件中。你可以找到类似下面的函数export function calculateCost(model: string, promptTokens: number, completionTokens: number): number { const modelRates { gpt-4: { input: 0.03, output: 0.06 }, // 每千令牌的价格美元 gpt-4-turbo-preview: { input: 0.01, output: 0.03 }, gpt-3.5-turbo: { input: 0.0005, output: 0.0015 }, // ... 其他模型 }; const rates modelRates[model]; if (!rates) return 0; const inputCost (promptTokens / 1000) * rates.input; const outputCost (completionTokens / 1000) * rates.output; return inputCost outputCost; }你可以更新这里的modelRates对象或者增加更复杂的逻辑比如根据用量阶梯计价。场景三增加数据导出功能后台的数据不能只停留在看有时需要导出做进一步分析。你可以增加一个CSV导出按钮。在后台页面如app/dashboard/page.tsx添加一个按钮。创建一个新的API路由如app/api/export/route.ts使用Prisma查询所需数据然后使用json2csv之类的库将数据转换为CSV格式。前端通过点击按钮调用这个API触发文件下载。避坑指南在修改涉及数据库的操作如修改schema后一定要记得运行npx prisma db push或npx prisma migrate dev来同步数据库结构。直接修改数据库而不更新Prisma客户端会导致运行时错误。4.3 生产环境部署建议本地跑通后如果你打算用于团队或生产环境需要考虑以下几点部署平台由于是Next.js应用部署到Vercel是最简单的选择几乎无缝衔接。也可以部署到任何能运行Node.js的服务器如AWS EC2、Google Cloud Run。数据库不要使用Docker Compose里的临时数据库。应该连接一个托管的PostgreSQL服务如AWS RDS、Supabase、Neon.tech或自建的稳定数据库实例。修改DATABASE_URL环境变量即可。安全加固确保NEXTAUTH_SECRET是足够复杂的随机字符串。在生产环境设置NEXTAUTH_URL为你的真实域名。考虑配置HTTPS。限制后台登录IP如果需要可以在NextAuth的配置中增加回调验证。性能与数据量日志数据会快速增长。建议定期如每月清理或归档旧日志。可以在Prisma Schema中为createdAt字段建立索引并优化查询语句避免在数据量大时仪表盘加载缓慢。5. 替代方案与项目局限性探讨虽然llm.report很优秀但我们必须客观看待其作为“归档项目”的局限性并了解当前生态中的其他选择。5.1 llm.report的局限性项目停滞最大的问题是无人维护。这意味着新的OpenAI模型如gpt-4o发布后其定价可能需要你手动更新代码。如果发现bug也需要自己修复。功能范围固定它专注于OpenAI API的日志和成本分析。对于更复杂的MLOps需求如模型性能监控、漂移检测、A/B测试平台集成等它无法提供支持。社区支持缺失你无法在GitHub Issues里获得作者的帮助只能依靠自己和开源社区如果有的话的零星讨论。5.2 主流替代方案对比方案类型核心优势核心劣势适用场景llm.report (自托管)开源归档项目功能专注、部署简单、UI美观、完全免费可控无人维护、功能不再更新个人开发者、小团队需要快速搭建一个免费、基础的OpenAI监控面板Langfuse开源可商用功能极其强大追踪、评估、提示词管理、活跃社区、支持多模型部署和配置更复杂、资源消耗更大中大型团队需要进行深入的LLM应用开发、评估和运维OpenAI 官方仪表盘官方服务无需部署、数据权威、实时性高功能简单仅成本和使用量、无用户级分析、日志保留时间短所有用户用于查看官方账单和基础用量Helicone商业服务/开源提供代理服务、功能丰富、有免费额度高级功能收费、数据经过第三方不想自托管且愿意接受SaaS服务的团队自研SDKBI工具自定义开发完全定制、与现有系统无缝集成开发成本高、需要投入运维有较强研发能力的大公司需要将LLM监控深度集成到内部平台5.3 如何选择与决策我的建议是分阶段考虑阶段一原型验证/个人项目直接使用llm.report。它的部署成本几乎为零能让你在半小时内获得远超OpenAI官方后台的洞察力快速验证成本结构和优化提示词。即使项目停了现有代码对于核心需求完全够用。阶段二产品成长/小团队当llm.report无法满足需求如需要团队协作、更复杂的分析时评估Langfuse。它是目前开源LLM观测领域的标杆虽然重一些但能为你后续的发展铺平道路。阶段三成熟产品/企业级考虑购买商业服务如Helicone的付费版或基于开源方案进行二次开发。此时稳定性和功能全面性比成本更重要。个人体会对于绝大多数中小项目llm.report提供的“成本-日志-用户关联”三板斧已经解决了80%的监控需求。它的“停更”状态反而使其成为一个稳定、可预期的工具。你不会担心它突然增加一个破坏性更新。你需要做的就是把它当作一个内部工具代码库拿过来部署好用起来。在它确实不够用的时候你积累的数据和经验也已经能帮你清晰地定义下一阶段需要什么。从这个角度看这个“宝藏”项目的价值才刚刚开始。