粗读阶段用 LiteParse 不花 Token，精读 VLM 走 TaoToken

1. 从 VLMPredictor 的 base_url 报错切入两遍式 OCR 为什么先 LiteParse 后 VLM如果你在 LlamaIndex 里配置VLMPredictor或OpenAIMultiModal时遇到401 Invalid API key先检查两个地方api_key是否来自可用渠道base_url是否指向https://taotoken.net/api。拿 Key 的入口在 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentllamaindex_ocr 。这篇文章不讨论“把整本 PDF 丢给 VLM”的粗放做法而是按 LlamaIndex 提出的 just-in-time Agentic OCR 思路把文档处理拆成两遍第一遍用 LiteParse 这类免费解析器粗读全部文件建立可检索索引第二遍只对检索命中的页面调用 VLM 做 OCR。TaoToken 在这里承担的是精读阶段的 VLM API 出口Base URL 固定为https://taotoken.net/apiKey 占位符统一写成YOUR_API_KEY。下面从成本观测视角把两阶段 Token 花费、LlamaIndex 配置、Claude Code/Codex 复用 Key 和排障步骤串起来。很多团队一开始做文档问答会直接走“每页图片 → 多模态 OCR → 文本入库”的流水线。这个方案精度上限高但成本也直观100 页 PDF 就是 100 次多模态调用如果每页输入 800 Token、输出 400 Token仅 VLM 阶段就是 80,000 输入 Token 40,000 输出 Token。真正被用户问题命中的页面可能只有 5 到 10 页其余 90 页的 OCR 结果在本次问答里根本不会被引用。两遍式 just-in-time Agentic OCR 的价值就在这里先用免费解析器把“全量文件”变成可检索的粗读索引再按问题动态决定哪些页面值得精读。LiteParse 粗读不花 VLM TokenVLM 精读走 TaoToken成本观测才有明确的分子和分母。配置前先明确边界粗读阶段的目标不是完美 OCR而是“找得到”。精读阶段的目标才是“读得准”。如果把这两个目标混在一起就会出现两种浪费一是用 VLM 做全量粗读Token 爆炸二是用免费解析器硬扛复杂表格检索命中率低精读阶段仍然找不到正确页面。所以本文的配置顺序是先在 TaoToken 官网拿到 Key设置好https://taotoken.net/api再在 LlamaIndex 里把 VLM 调用限制在命中页面上。下面每一步都可以本地复现。2. LiteParse 粗读把“全量文件”变成 0 Token 的检索索引LiteParse 这类免费解析器的核心作用是把 PDF、图片、Office 文档里的可见文本尽量抽取出来不调用远端多模态大模型。它可能对复杂表格、扫描件、手写体不够准但足够支撑第一层检索文件路径、页码、标题、正文片段。粗读阶段不消耗 VLM Token消耗的是本地 CPU、内存和 I/O。对于成本观测来说这一阶段可以记为 0 Token如果你在粗读后还接了嵌入模型做向量索引嵌入成本要单独计算不要和 VLM OCR 混在一张表里。在 LlamaIndex 里你可以先用SimpleDirectoryReader模拟粗读加载再替换成 LiteParse 的输出。关键是保留file_path和page_label两个元数据因为精读阶段需要根据命中节点反查原始页面图片。示例代码from llama_index.core import SimpleDirectoryReader, VectorStoreIndex, Settings from llama_index.core.node_parser import SentenceSplitter # 粗读阶段本地解析不调用 VLM Settings.node_parser SentenceSplitter(chunk_size512, chunk_overlap64) documents SimpleDirectoryReader( input_dir./docs, recursiveTrue, required_exts[.pdf, .png, .jpg, .docx] ).load_data() # 如果使用 LiteParse在这里把 documents 替换成 LiteParse 输出的 Document 列表 index VectorStoreIndex.from_documents(documents) retriever index.as_retriever(similarity_top_k6) hits retriever.retrieve(违约金 计算 方式 逾期 利息) for i, node in enumerate(hits, 1): print(命中, i) print(文件:, node.metadata.get(file_path)) print(页码:, node.metadata.get(page_label)) print(片段:, node.text[:200]) print(---)这段代码的 Token 成本是 0不计嵌入。它把“全量文件”变成可检索节点后续问题先在这里找相关页。成本观测视角下粗读阶段要记录三个指标总文件数、总页数、命中页数。总页数决定如果全量 VLM 会有多贵命中页数决定两遍式实际精读多少页。很多成本争议不是模型单价造成的而是“命中页数”没有被单独统计。粗读阶段还有两个工程细节容易被忽略。第一页码映射。扫描版 PDF 的物理页码和文档内页码可能不一致精读时如果按page_label找不到图片就会出现“检索命中但无法精读”的情况。建议在粗读元数据里同时保留page_index和page_label。第二分块粒度。块太大检索命中后需要精读多页块太小关键上下文被切碎。对于合同、论文、说明书512 到 1024 Token 的块大小通常更容易做成本控制因为命中页数不会因为分块过碎而膨胀。完成粗读后可以把命中节点按(file_path, page_index)去重得到“待精读页面列表”。这个列表就是下一阶段调用 TaoToken VLM 的输入。不要直接把所有节点丢给 VLM也不要让 Agent 自由决定“再读几页”否则成本观测会失控。更稳的做法是检索返回 Top K去重后限制最多 N 页比如 Top 6 去重后最多 4 页。这样每次问答的 VLM 调用次数有上限成本可预测。3. 精读阶段接入 TaoTokenLlamaIndex VLM 配置与 Base URL 写法精读阶段才真正调用 VLM。配置前先去 TaoToken 官网创建 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentllamaindex_ocr 。然后在本地环境变量里写入占位符替换后的 Keyexport TAOTOKEN_API_KEYYOUR_API_KEYLlamaIndex 的多模态调用通常从OpenAIMultiModal或同类 VLM Predictor 进入。关键配置只有两个api_key使用你的 TaoToken Keybase_url使用https://taotoken.net/api。注意 Base URL 不加 UTM 参数它是工具配置项带 UTM 的链接只用于网页入口。import os from llama_index.multi_modal_llms.openai import OpenAIMultiModal from llama_index.core.schema import ImageDocument vlm OpenAIMultiModal( modelgpt-4o-mini, # 以 TaoToken 控制台可用模型名为准 api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api, max_new_tokens1024, temperature0.1, ) image_doc ImageDocument(image_path./pages/page_017.png) resp vlm.complete( prompt请对这张页面做 OCR保留表格结构输出 Markdown。不要翻译不要总结。, image_documents[image_doc], ) print(resp.text)如果你的 LlamaIndex 版本里参数名不是base_url而是api_base按你本地版本替换即可。核心不变请求出口指向 TaoTokenKey 用YOUR_API_KEY所在的环境变量。精读阶段的 prompt 要尽量稳定建议固定成三段第一段说明“只做 OCR不翻译不总结”第二段说明“表格用 Markdown 表格公式用 LaTeX”第三段说明“如果图片模糊输出[模糊]标记不要编造”。这样做的好处是输出长度可控成本可预测后续解析也稳定。把粗读命中的页面批量送入 VLM 时建议加并发限制和页数上限import time from concurrent.futures import ThreadPoolExecutor, as_completed hit_pages [ ./pages/page_017.png, ./pages/page_023.png, ./pages/page_024.png, ] def ocr_one(path: str): doc ImageDocument(image_pathpath) t0 time.time() resp vlm.complete( prompt请对这张页面做 OCR保留表格结构输出 Markdown。不要翻译不要总结。, image_documents[doc], ) return { path: path, elapsed: round(time.time() - t0, 2), text: resp.text, raw: resp.raw if hasattr(resp, raw) else None, } results [] with ThreadPoolExecutor(max_workers2) as pool: futures [pool.submit(ocr_one, p) for p in hit_pages] for f in as_completed(futures): results.append(f.result()) for r in results: print(r[path], r[elapsed], len(r[text]))max_workers2到4是较稳的起点。并发太高容易触发限流精读阶段本来就不需要把 100 页全部并发跑完只处理命中页即可。这里再次强调成本观测粗读阶段的命中页数、精读阶段的输入 Token 和输出 Token要分别记录。TaoToken 官网控制台与 API Keys 页面可以用于创建和管理 Key入口在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentllamaindex_ocr 。如果你需要在网页里先验证模型对话是否正常可以走模型对话 deep link文末会按路径给出。4. 两阶段 Token 花费对照表100 页 PDF 的实测口径下面给出一张可复现的两阶段 Token 花费对照表。数据用 100 页扫描 PDF、每页 VLM 输入约 800 Token、输出约 400 Token、检索命中 6 页作为示例。你只需要把页数、命中页数、输入输出估算替换成自己的实测值即可。表里的“Token”只统计 VLM 多模态调用不含本地解析和嵌入模型。方案处理范围VLM 调用页数输入 Token 估算输出 Token 估算成本观测说明全量 VLM OCR100 页全部100100 × 800 80,000100 × 400 40,000每页都进多模态成本随总页数线性增长两遍式LiteParse 粗读100 页本地解析000建立检索索引不调用 VLM两遍式VLM 精读命中 6 页66 × 800 4,8006 × 400 2,400只 OCR 检索命中的页面两遍式合计100 页文档64,8002,400相比全量 VLM输入约为 6%输出约为 6%上面的比例不是承诺值而是算例。实际节省取决于命中率。如果 Top K 检索经常命中 30 页精读成本仍然会接近全量如果命中 3 页节省更明显。成本观测要做的是把“命中页数 / 总页数”作为核心指标而不是只盯模型单价。建议每次问答记录总页数100 粗读耗时本地 12.4s 粗读 VLM Token0 检索 Top K6 去重后精读页数4 精读输入 Token3,200 精读输出 Token1,600 本轮总 VLM Token4,800为了从 API 返回里拿到用量可以这样统计total_in 0 total_out 0 for page in hit_pages: resp vlm.complete( prompt请对这张页面做 OCR保留表格结构输出 Markdown。不要翻译不要总结。, image_documents[ImageDocument(image_pathpage)], ) usage {} if isinstance(resp.raw, dict): usage resp.raw.get(usage, {}) total_in usage.get(prompt_tokens, 0) total_out usage.get(completion_tokens, 0) print(输入 Token:, total_in) print(输出 Token:, total_out)如果resp.raw的结构与你的 SDK 版本不同以实际返回对象为准。重点是把“粗读 0 Token、精读按页计费”拆开。表格落地后你会发现成本控制的抓手不是换更便宜的模型而是减少无效精读页数。粗读索引的质量、去重策略、Top K 和每轮最大页数都会直接影响最终 Token 花费。5. Claude Code、Codex、CC Switch 如何复用同一个 TaoToken KeyLlamaIndex 的 VLM 精读只是其中一条链路。日常开发里你可能还会用 Claude Code 跑仓库任务用 Codex 做代码补全或终端 Agent用 CC Switch 管理多套配置。为了不让 Key 散落在多个文件里建议统一从 TaoToken 官网创建 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentllamaindex_ocr 。然后按工具各自的配置格式填写不要把ANTHROPIC_*套到 Codex也不要把 Codex 的config.toml写进 Claude Code。Claude Code 使用settings.json和ANTHROPIC_*环境变量。一个可复制的配置如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }把这段放到 Claude Code 对应的settings.json后重启会话。注意ANTHROPIC_BASE_URL指向https://taotoken.net/api不要多写/v1也不要带 UTM 参数。Key 占位符替换成你自己的值。Codex 使用config.toml配置模型供应商时用 Codex 自己的字段不要混入ANTHROPIC_*model_provider taotoken model gpt-4.1 [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY然后在本地设置环境变量export TAOTOKEN_API_KEYYOUR_API_KEY这样 Codex 会从TAOTOKEN_API_KEY读取 KeyBase URL 仍然是https://taotoken.net/api。如果你的 Codex 版本要求env_key使用OPENAI_API_KEY按你本地版本文档调整环境变量名但不要让 Claude Code 的ANTHROPIC_*出现在 Codex 配置里。CC Switch 可以理解为多套 API 配置的切换面板。把它当作“三件套”来填即可供应商名称TaoToken Base URLhttps://taotoken.net/api API KeyYOUR_API_KEY这样 LlamaIndex、Claude Code、Codex 可以共用同一套 TaoToken 出口但建议按项目或按用途创建不同 Key。比如llamaindex-ocr一个 Keyclaude-code一个 Keycodex一个 Key。成本观测时你可以从 API Keys 页面按 Key 维度看用量排查是 OCR 精读花得多还是代码 Agent 花得多。API Keys 管理入口https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentllamaindex_ocr 。6. VLM 精读排障401/404/429、超时与返回格式精读阶段一旦接入 TaoToken常见报错集中在认证、路径、限流和输出解析四类。下面按成本观测视角给出排查顺序。第一类401或Invalid API key。先确认YOUR_API_KEY是否真的被环境变量替换。可以在本地执行python -c import os; print(os.environ.get(TAOTOKEN_API_KEY, MISSING)[:8])如果输出MISSING说明环境变量没进到当前进程。不要把 Key 写死在代码里提交到仓库。第二类404或model not found。先检查 Base URL 是否为https://taotoken.net/api不要写成https://taotoken.net/api/v1或https://taotoken.net/。再检查模型名是否在 TaoToken 控制台可用。模型名以控制台展示为准不要直接复制其他平台的模型 ID。第三类429或并发限流。精读阶段只处理命中页本来就不该高并发。把ThreadPoolExecutor(max_workers2)作为起点如果仍然触发限流降到 1并加入指数退避import time def complete_with_retry(vlm, prompt, image_doc, retries3): for i in range(retries): try: return vlm.complete(promptprompt, image_documents[image_doc]) except Exception as e: msg str(e) if 429 in msg or rate in msg.lower(): wait 2 ** i print(f限流等待 {wait}s 后重试) time.sleep(wait) continue raise raise RuntimeError(重试失败)第四类超时或输出被截断。大图先做压缩宽度控制在 1600 到 2000 像素max_new_tokens不要无限放大OCR 输出通常 512 到 1024 足够。如果表格特别复杂可以分页分块 OCR而不是一页要求输出全部内容。第五类返回格式不是 Markdown。检查 prompt 是否明确要求“输出 Markdown不要额外解释”。你可以在解析前加一层清洗def clean_ocr_text(text: str) - str: text text.strip() if text.startswith(markdown): text text[len(markdown):].strip() if text.endswith(): text text[:-3].strip() return text排障时还要区分“粗读失败”和“精读失败”。如果检索根本没命中正确页面精读再强也没用如果命中页正确但 VLM 返回乱码优先检查图片清晰度、prompt 和模型名。成本观测上粗读失败不会增加 VLM Token但会增加重复精读精读失败会增加重试 Token。建议把每次精读的page_path、elapsed、prompt_tokens、completion_tokens、retry_count打到本地日志方便回看。7. 文末 CTA 路径从模型对话到 Claude Code 文档把两遍式 OCR 跑通后建议按下面路径完成 TaoToken 配置和验证。顺序是先模型对话验证模型可用再看 Coding Plan然后创建 Key最后按 Claude Code 文档接入开发环境。模型对话入口https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentllamaindex_ocr如果你要长期跑 OCR、文档 Agent 或 Coding AgentCoding Plan 入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentllamaindex_ocr创建和管理 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentllamaindex_ocrClaude Code 配置文档https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentllamaindex_ocr回到本文的核心结论粗读阶段用 LiteParse 不花 VLM Token精读阶段只对检索命中的页面调用 TaoToken VLMBase URL 设为https://taotoken.net/apiKey 占位符用YOUR_API_KEY。按第 4 节的对照表记录总页数、命中页数、输入 Token、输出 Token你就能把“精度提升”和“成本增加”放在同一张表里决策。下次遇到VLMPredictor认证或路径报错时先查 Key 和 Base URL再查命中页数是否失控。两遍式 just-in-time Agentic OCR 不是魔法它只是把昂贵的 VLM 调用从“全量预读”改成了“按需精读”而成本观测正是这套流程能不能持续跑下去的关键。