LiteRT-LM调试技巧清单实验性API与运行时调试器快速定位问题【免费下载链接】LiteRT-LMLiteRT-LM is Googles production-ready, high-performance, open-source inference framework for deploying Large Language Models on edge devices.项目地址: https://gitcode.com/GitHub_Trending/li/LiteRT-LMLiteRT-LM是 Google 开源的高性能 LLM 端侧推理框架。当模型输出异常、速度不达标时本文教你用 LiteRT-LM 的两大利器——运行时调试器RuntimeDebugger与实验性 APIExperimental API——快速定位问题3 步开启张量转储、读懂 token 轨迹日志、排查工具调用与推测解码配置。一、先认识 LiteRT-LM 的两大调试利器 LiteRT-LM 把调试能力封装成了两个清晰的入口组件作用所在位置运行时调试器 RuntimeDebugger捕获中间层张量、逐步记录生成 token 与置信度runtime/util/runtime_debugger.h实验性 APIExperimental会话调试信息、基准测试、受控解码等不稳定但强大的功能C APIc/experimental.hSwiftswift/ExperimentalFlags.swift运行时调试器给推理过程装上行车记录仪RuntimeDebugger 会做两件事见runtime/util/runtime_debugger.cc张量捕获在每次计算图执行前后把关键激活张量以 HuggingFaceSafetensors格式落盘文件名带pre_/post_前缀和步数编号Token 轨迹把每步生成的token_ids、texts、scoressoftmax 置信度追加写入generated_tokens.jsonl推理结束kDone / 达到最大 token 数时还会把 KV-Cache 同步落盘。这样当模型说错话时你可以回看是哪一步、哪个张量开始偏的。实验性 API显式opt-in按需启用实验性接口刻意被隔离避免误用。在 Swift 侧swift/ExperimentalFlags.swift必须先调用ExperimentalFlags.optIntoExperimentalAPIs()才能设置以下常用调试/调优标志enableBenchmark开启基准测试拿到首 token 时延、prefill/decode 吞吐BenchmarkInfoenableConversationConstrainedDecoding函数调用受控解码排查工具调用格式错误enableSpeculativeDecoding推测解码开关visualTokenBudget视觉 token 预算70/140/280/560/1120enableConversationToolCallStreaming工具调用流式输出⚠️ 注意多数标志只在新建 Engine / Conversation 时读取改完对已有实例不生效——调试时请先关闭再重建会话。二、3 步启用运行时调试器最快上手方法⚡第 1 步编译时开启调试器宏调试器是编译期开关构建时加上--define LITERT_LM_DEBUGGER_ENABLED1相关条件编译集中在c/experimental.cc与runtime/core/engine_advanced_impl.cc宏未开时整个后端被剔除零运行时开销。第 2 步确认调试器可用Python 侧可直接查询python/litert_lm/session.py、python/litert_lm/conversation.pyimport litert_lm print(litert_lm.Session) # 你的会话对象 artifacts session.get_debug_artifacts()若运行时未启用宏get_debug_artifacts()会返回None并给出RuntimeWarning提示补上编译参数——这是最常见的为什么拿不到调试文件原因。第 3 步从会话中取出调试产物get_debug_artifacts()返回DebugArtifacts数据类定义在python/litert_lm/interfaces.py包含两个字段tensor_paths该会话所有 Safetensors 张量转储路径已排序trace_log_pathtoken 轨迹日志JSONL路径产物统一存放在缓存目录下的litert_lm_debugger/session_id/子目录中目录名逻辑见runtime/util/runtime_debugger.cc中的kDebuggerSubdir常量。完整行为可用测试文件python/litert_lm/debug_artifacts_test.py对照验证。三、读懂调试产物张量转储 token 轨迹日志 拿到产物后按这个顺序排查最高效先看generated_tokens.jsonl逐行是每步的token_ids、texts、scores。低分如 0.5出现在哪一行往往就是模型跑偏的起点再查对应的 Safetensors文件名形如signature_pre|posttensor_step_n.safetensorssignature中含prefill的属于预填充阶段其余属于解码阶段。用任何 Safetensors 加载器即可查看数值对照正常运行的快照找异常步最后核对 KV-Cache推理结束时同步落盘的 KV 缓存可用于复现/热启动分析。 技巧对比一次正常会话与一次异常会话的scores序列通常前 3 步就能看出输入模板或分词差异是否引入了问题。四、性能问题就用实验性 Benchmark 接口定位 怀疑慢而不是错时开启实验性基准测试BenchmarkInfopython/litert_lm/interfaces.py会给出init_time_in_second引擎与会话初始化耗时time_to_first_token_in_second首 token 时延TTFTlast_prefill_tokens_per_second/last_decode_tokens_per_second最近一轮 prefill / decode 吞吐Kotlin 侧同样提供基准能力kotlin/java/com/google/ai/edge/litertlm/Engine.kt中的实验性接口iOS/macOS 示例见samples/ios_and_mac/。五、工具调用输出异常看这张流程图与解析图 工具调用Tool Calling输出格式错误是高频问题。先理解官方定义的调用流程排查清单是否启用了enableConversationConstrainedDecoding受控解码可强制输出符合工具格式Swift 侧是否默认把 camelCase 工具名转成了 snake_caseconvertCamelToSnakeCaseInToolDescription模型更熟 snake_case 时建议保持默认true用 JSONL 轨迹中的scores确认模型是否在工具 JSON 结构处置信度骤降API 细节参考文档docs/api/cpp/tool-use.md、docs/api/cpp/constrained-decoding.md。六、注意事项与最佳实践 ✅调试有成本张量转储写盘会显著拖慢推理并占用磁盘只在问题复现路径上开启且指定独立cache_dir内存缓存模式下调试器不可用:memory缓存目录不会产出调试文件见c/experimental.h中 capture dir 说明实验性 API 不保证稳定c/experimental.h明确声明可能随时变更或移除生产代码不要依赖其签名C API 用户拿到LiteRtLmSessionDebugInfo*后务必调用litert_lm_experimental_session_debug_info_delete释放内存取调试目录用..._get_capture_dir。总结症状首选调试手段输出内容错误/乱码generated_tokens.jsonl 对应步的 Safetensors工具调用格式错误受控解码实验标志 流程图对照速度慢实验性 BenchmarkTTFT / prefill / decode 吞吐视觉输入异常visualTokenBudget实验标志掌握运行时调试器张量级证据链实验性 API会话级开关与基准数据这套组合拳LiteRT-LM 在端侧的绝大多数疑难问题都能在几分钟内缩小到具体步骤而不是在玄学里打转。祝调试顺利 【免费下载链接】LiteRT-LMLiteRT-LM is Googles production-ready, high-performance, open-source inference framework for deploying Large Language Models on edge devices.项目地址: https://gitcode.com/GitHub_Trending/li/LiteRT-LM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考