1. 上线后的 LLM 应用为什么总在“裸奔”你有没有过这种体验本地跑一个基于大模型的问答机器人来回测了十几轮感觉回答都挺像样结果一上线用户第一句就问出个离谱答案。更尴尬的是你打开日志只看到一行200 OK模型当时检索了哪些文档、调用了哪个工具、中间那步是不是把上下文串了全都没留下痕迹。这不是个别现象。LLM 应用天生带“黑盒”属性输出不确定、调用链多步嵌套Agent 里套工具工具里再调模型传统print和普通日志在这种结构面前基本失效。你缺的不是更聪明的模型而是一套能看清内部、还能自动回归的工程设施——也就是给 AI 应用装上“仪表盘”和“测试架”。Opik 就是干这个的。它是一个开源的 LLM 应用全生命周期平台覆盖 Trace 追踪、在线监控、数据集评测和 Prompt 管理Apache-2.0 协议服务端和前端都能自己部署。这篇不聊概念直接给你一套可复制的接入骨架从拿 Key、初始化项目到跑通一条 LLM 调用并在仪表盘里看到 trace 和评估分数。适合正在把 LLM 应用从 demo 推向生产的工程师也适合被“上线就翻车”折磨过的团队。2. 前置准备TaoToken 与 Opik 的分工在动手之前先把两个东西的角色分清楚不然后面配置容易乱。TaoToken 在这里承担的是模型调用入口。你的 LLM 请求走它的 API好处是 Key 和地址统一管理切换模型时不用改一堆环境变量。Opik 则负责观测和评测它不关心你调的是哪家模型只负责把每次调用的输入、输出、耗时、token 消耗记录下来并支持你挂上评估指标。所以整体链路是你的代码 → TaoToken API模型调用→ Opik SDK追踪上报→ Opik 仪表盘查看 trace 与分数。你需要准备两样东西第一TaoToken 的 API Key。登录官网后进入控制台在 API Keys 页面创建一个新 Key复制保存。注意它只显示一次丢了就重新建。第二Opik 的服务地址。如果你用云端版注册后拿到 API Key 和 workspace 名称如果自托管本地起服务后地址通常是http://localhost:5173API 端点是http://localhost:5173/api。这篇以自托管为例云端版把地址换成对应域名即可。提示自托管建议用 Docker 起官方仓库里有opik.sh脚本Linux/Mac 直接跑Windows 用 WSL 或 Docker Desktop 都行。数据留在自己内网合规上省心。3. 可复制配置Opik 接入骨架这一节是核心给你一份能直接抄的配置骨架。分三步装依赖、初始化 Opik、包住你的 LLM 调用。3.1 安装依赖与环境变量先建一个干净的 Python 环境装两个包pip install opik openaiopik是观测 SDKopenai用来发模型请求TaoToken 兼容 OpenAI 协议所以直接用 openai 客户端即可。然后在项目根目录建一个.env文件把 Key 和地址集中放# .env TAOTOKEN_API_KEY你的_taotoken_key TAOTOKEN_BASE_URLhttps://taotoken.net/api OPIK_API_KEY你的_opik_key OPIK_WORKSPACE你的_workspace OPIK_URL_OVERRIDEhttp://localhost:5173/api如果你用云端 OpikOPIK_URL_OVERRIDE可以删掉SDK 会走默认云端地址。自托管必须显式指定否则它会往云端发。3.2 初始化 Opik 与模型客户端新建main.py先做初始化import os from dotenv import load_dotenv from opik import Opik from openai import OpenAI load_dotenv() # 初始化 Opik 客户端 opik_client Opik( api_keyos.getenv(OPIK_API_KEY), workspaceos.getenv(OPIK_WORKSPACE), url_overrideos.getenv(OPIK_URL_OVERRIDE), ) # 初始化模型客户端指向 TaoToken llm_client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), )这里Opik()的url_override是关键参数自托管场景下不填会连不上。workspace在自托管里可以随便填一个名字云端版必须和后台一致。3.3 用装饰器包住调用链Opik 最省事的地方是track装饰器。你把它加在函数上函数内部的 LLM 调用、检索、工具调用会自动嵌套成一条 trace。from opik import track track def ask_llm(question: str) - str: response llm_client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: question}, ], temperature0.2, ) return response.choices[0].message.content注意track加在函数上之后Opik 会自动捕获这次调用的输入question、输出content以及耗时和 token 用量。如果你有多层函数比如ask_llm里再调一个retrieve_docs只要那个函数也加了track它们会形成父子节点在仪表盘里就是一棵树。3.4 挂一个评估指标光有 trace 还不够你要能自动打分。Opik 内置了一批 LLM-as-a-Judge 指标比如幻觉检测、答案相关性。下面挂一个幻觉检测from opik.evaluation.metrics import Hallucination hallucination_metric Hallucination() def evaluate_answer(question: str, answer: str, context: list[str]): score hallucination_metric.score( inputquestion, outputanswer, contextcontext, ) return scorescore返回一个对象里面有分值和理由。你可以把它写回 trace也可以单独存成数据集跑实验。这里先手动调一次验证链路通不通。4. 端到端验证跑通一条调用并看到 trace配置写完了现在跑一次完整流程确认仪表盘里能看到东西。4.1 执行脚本在main.py末尾加上主逻辑if __name__ __main__: question 法国首都是哪里 answer ask_llm(question) print(模型回答, answer) result evaluate_answer( questionquestion, answeranswer, context[法国是欧洲国家首都是巴黎。], ) print(幻觉检测分数, result.score) print(评分理由, result.reason)运行python main.py终端应该输出类似模型回答 法国首都是巴黎。 幻觉检测分数 0.0 评分理由 输出与上下文一致未发现幻觉。分数 0.0 表示没有幻觉不同指标定义不同有的 0 是最好有的 1 是最好看指标文档。4.2 在仪表盘确认 trace打开浏览器访问http://localhost:5173进入你的 workspace。左侧菜单点 Traces你应该能看到刚才那条记录名字就是ask_llm。点进去能看到输入法国首都是哪里输出法国首都是巴黎。耗时几百毫秒到一两秒token 用量prompt 和 completion 分别多少如果有多层track这里会显示树状调用图再点 Evaluations 或 Metrics 标签能看到你挂的幻觉检测分数和理由。到这一步说明从模型调用到追踪上报再到评估打分的链路全通了。注意如果 Traces 页面是空的先检查OPIK_URL_OVERRIDE是否指向了正确的 API 地址以及 Opik 服务是否在运行。自托管常见问题是端口写错比如把前端 5173 当成 API 端口实际 API 是 5173/api。4.3 把评测接进 CI 的思路单次跑通只是开始。真正让它变成“测试架”的做法是把上面这套逻辑包成一个脚本在 CI 里每次提交自动跑一遍测试集分数低于阈值就 fail。Opik 支持把数据集存成 Dataset用 Experiment 批量跑这里不展开但思路就是线上采集真实请求 → 存成数据集 → 每次发版前跑一遍 → 对比分数。5. 本篇常见错排查接入过程中最容易卡住的几个点我列出来你对照着查。报错一Connection refused或 trace 不上报。九成是OPIK_URL_OVERRIDE没设或设错。自托管必须写成http://localhost:5173/api注意结尾的/api。云端版则要确认OPIK_API_KEY和OPIK_WORKSPACE都填了。报错二模型调用 401。检查TAOTOKEN_API_KEY是否复制完整以及base_url是不是https://taotoken.net/api。注意结尾不要多加/v1OpenAI 客户端会自动拼路径多写反而 404。报错三track加了但仪表盘只有一层。说明你的嵌套函数没加装饰器。Opik 只追踪被track标记的函数普通函数调用不会自动进树。把内层函数也加上即可。报错四评估指标报context缺失。幻觉检测这类指标依赖context参数如果你没传它会报错或给无意义分数。确保调用score()时把检索到的文档传进去。报错五自托管启动后前端打不开。先确认 Docker 容器都起来了docker ps看有没有异常退出的。首次启动拉镜像可能慢等一两分钟再刷新。6. 下一步把观测变成习惯跑通这一条 trace 之后你可以做两件事让它真正产生价值。一是把track加到项目里所有关键函数上尤其是检索、工具调用、多轮 Agent 这些容易出错的环节让每次线上请求都留下完整调用链。二是把评估脚本接进 CI每次改 prompt 或换模型都自动跑一遍测试集用分数而不是感觉来判断有没有退步。如果你还在用print和几个手写用例验证 LLM 应用建议先花半小时把上面这套骨架跑起来。它不会让模型变聪明但会让你清楚知道它什么时候错、错在哪一步。需要 Key 和接入文档的话可以从这里开始模型对话与调试https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你打算长期做编码类或 Agent 类应用可以看看 Coding Plan把模型调用和观测链路一起管起来https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite