跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
AI 与知识库

litert-conversion-workflow

Convert a Hugging Face LLM or vision-language model checkpoint into a .litertlm bundle that runs on the LiteRT-LM runtime with verified quality - classify the architecture against known runtime walls, pick the recipe family (dense, reasoning, hybrid SSM, VLM), export, quantize, gate the result against the source model, and publish. Use when converting a new LLM or VLM to LiteRT-LM, when a converted bundle crashes on the first message or dies at engine creation, when a quantized model answers worse than its source, or when deciding whether a model is convertible at all.

google-ai-edge · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add google-ai-edge/litert-samples --skill litert-conversion-workflow

技能说明


name: litert-conversion-workflow description: Convert a Hugging Face LLM or vision-language model checkpoint into a .litertlm bundle that runs on the LiteRT-LM runtime with verified quality - classify the architecture against known runtime walls, pick the recipe family (dense, reasoning, hybrid SSM, VLM), export, quantize, gate the result against the source model, and publish. Use when converting a new LLM or VLM to LiteRT-LM, when a converted bundle crashes on the first message or dies at engine creation, when a quantized model answers worse than its source, or when deciding whether a model is convertible at all.

LiteRT-LM conversion workflow

A conversion is done when three things hold, in this order:

  1. the bundle loads and generates through the LiteRT-LM engine (not just the raw interpreter),
  2. output quality is gated against the source model — a floor gate plus a task-level parity check, not a smoke test,
  3. it holds up on the deployment path it claims: the target backend, the target device, and multi-turn conversation.

Each step can pass while the next one fails. A bundle that converts can die at engine creation; an engine that generates can be quantization garbage; a model that answers 8/8 single-turn can crash on message two. The gates exist because every one of these has happened.

Scope: models producing a .litertlm bundle consumed by the LiteRT-LM engine (pip install litert-lm) — text LLMs and vision-language models (a VLM bundle is an LLM bundle plus two vision graphs; references/vlm-conversion.md covers the delta). Standalone/classic .tflite models go through the gpu-clean-conversion → accuracy-safe-quantization → on-device-verification lane; this skill is the LM sibling and reuses their discipline where it applies.

Step 0: classify before you convert

Look at config.json (model_type, layer_types, MoE fields, size) before running anything. Architecture decides everything downstream, and some structures die at a known point no recipe can route around. references/architecture-walls.md is the lookup table: structure → where it dies (export / load / engine / backend) → the error signature you'll see. Check it first; it turns a day of debugging into a table lookup.

Then pick the lane in references/recipe-selector.md: plain dense decoders ride a standard export; hybrids (SSM / linear-attention / short-conv) need state-aware export plus executor metadata; reasoning models need template care; MoE and MLA are currently walls.

Loop

1. Export with a minimal, extraction-safe template. The single most common ship-killer is not math — it is the chat template. Export with use_jinja_template=False and a minimal ChatML-style template swapped in, so the bundle carries plain prefix/suffix markers and no Jinja at all. Vendor templates routinely call Python methods (.get(), .startswith(), .strip()) that the runtime's minijinja renderer does not implement — such a bundle imports fine and dies on the first message. Details, the multi-turn prefix contract, and the tokenizer traps that pair with this: references/template-tokenizer-traps.md.

2. Check the bundle before measuring anything.

python -m litert_lm_builder.litertlm_peek_main --litertlm_file model.litertlm

prompt_templates-only = safe. A jinja_prompt_template carrying Python-method calls = the first-message crasher. Also confirm the stop tokens and (for hybrids) the executor-metadata section are present.

3. Quantize on the LLM lane. int8 dynamic is the safe default; int4 must be blockwise (block-32 quality, block-128 for ~4B / iPhone section limits) — channelwise int4 collapses decoders while still passing smoke tests. Conv/scan layers of hybrids stay float. The decision facts and the recipe mechanics: references/recipe-selector.md §Quantization, plus the accuracy-safe-quantization skill for the general ladder.

4. Gate quality — floor, parity, then structure. Run the gate stack in references/verification-gates.md:

  • 8-question floor gate on the engine (CPU, then the target backend). Catches collapse, never proves parity.
  • Task parity (e.g. GSM8K n≥100) against the source model, same prompt and extraction both sides. Reasoning models need max-tokens ≥ 2048 or int4 falsely looks degraded.
  • First-token length sweep — chat-templated prompt lengths are chunked by the engine's prefill planner, and state-carrying models corrupt at specific lengths while answering perfectly at others.
  • Multi-turn — single-turn evals structurally cannot catch template-contract violations that kill message two.

5. Gate on the target device. Desktop GPU pass ≠ mobile GPU pass (different delegates, different compilers). Record device, backend, runtime version, and speeds next to the quality numbers — the on-device-verification skill's rules apply unchanged.

6. Publish behind the gate. The upload step must mechanically refuse unless the quality report passed — a collapsed quant that reaches a public repo costs more than every hour the gates cost. Card conventions and the publish checklist: references/verification-gates.md §Publish.

Symptom router

What you seeWhere to look
Export raises in torch.export / tracingarchitecture-walls.md — data-dependent guards (MoE gating, dynamic rope), dtype-in-constant-path traps
Export OK, engine creation fails: No KV cache inputs foundHybrid on a pre-0.15 runtime — runtime too old for the architecture
Engine OK, generation dies: NOT_FOUND ... missing some output TensorBuffersHybrid bundle missing the executor-metadata section (recipe-selector.md §Hybrids)
First message crashes: unknown method: map has no method named getVendor Jinja embedded in the bundle — re-export per Loop step 1
Output is fluent garbage / prompt seems ignoredTokenizer packaging (template-tokenizer-traps.md §Tokenizer)
Runtime
阅读完整来源 ↗