1. AI 应用报错的特殊性先建立三层归因思维做AI应用开发这几年我最大的感受是报错从单选题变成了多选题。传统Web开发里报错通常是确定的——数据库连不上就是地址或账号问题语法错误就是代码写法问题搜一下几乎都有标准答案。但AI应用不一样模型输出自带随机性整条链路又特别长前端、后端、模型API、向量库、工具调用、日志系统全串在一起一个异常往往是两三个因素叠加后的结果。同样是API调用超时可能是你的prompt太长导致服务端预处理变慢也可能是模型服务端那一刻负载过高还可能是本地代码库版本太老把重试逻辑拖进了死循环。再比如JSON解析失败可能是你的代码解析逻辑写错了但更常见的是模型这次输出抽风在合法JSON外面裹了一层Markdown代码块。所以我要先给一套排错方法论不要急着搜报错文本先分清楚这个报错来自哪一层。1.1 报错从单选题变成多选题的底层原因报错变复杂底层原因无非三层。第一层是模型层。模型本身是概率输出同样的请求这次给你合法JSON下次就在里面插一句废话这次正常调用下次因为服务端限流返回429。模型层错误的特征是偶发、难以稳定复现重试一次往往就好了但如果不做防护它在线上会以固定概率不断出现日活越大问题越刺眼。第二层是链路层。链路层问题出在你自己的代码和系统设计上结构化输出没开、工具函数参数没校验、RAG分块不合理、向量维度写死、Agent没有终止条件。链路层错误的特征是稳定复现只要把触发条件跑一遍它必然爆。这类问题最折磨人因为责任完全在自己这边模型服务商帮不了你。第三层是工程层。这一层跟AI逻辑没关系纯粹是框架、编译、部署的坑比如Vite项目里报process is not definedWindows上做Tauri打包报link.exe not foundNode版本与构建工具链不匹配。工程层错误的特点是出现时机特别巧往往在你准备上线的前一晚突然冒出来。1.2 三层归因判断法用三个问题锁定方向报错出现时先问自己三个问题。第一个问题能稳定复现吗连续触发三次每次都报同样的错大概率是链路层优先检查自己的代码复现不出来基本就是模型层的随机性或服务端偶发故障。这个判断能直接砍掉一半排查时间。第二个问题报错文本里有没有明确的HTTP状态码或平台错误码比如401、403、429这些状态码直接去查对应平台的API文档不要自己瞎猜。自由格式的文本报错比如JSONDecodeError、Dimension Mismatch多半来自链路层回到代码里找问题。第三个问题如果完全不碰AI的代码纯静态页面或纯后端接口会不会报这个错如果会说明是工程层先解决工程问题再回来调AI逻辑不然很容易在AI代码里浪费大量时间。这三个问题的顺序就是我的标准排错顺序先复现、再归类、最后最小化。最小化复现这一条尤其重要——把请求简化到只有一个system消息、一个user消息去掉工具调用、去掉历史记忆、去掉RAG检索如果报错消失了就一层层加回来加一层测一次很快就能定位到是哪一步引入了问题。1.3 排查前三板斧复现、看原文、留样本说点实际经验。我见过太多同事拿着SDK包装后的异常信息来问问题比如OpenAI库抛了个BadRequestError我该怎么办但我把原始响应打印出来才发现根本问题是prompt超长被服务端拒绝SDK包装后的信息把关键内容吞掉了。所以第一板斧永远先看原始HTTP响应至少要打印response.text或者resp.model_extra别只看SDK转译后的异常。第二板斧每次报错都要保留完整的请求快照包括模型版本、请求参数、原始响应、时间戳。AI应用的报错是概率性的没有快照你根本没法复现没复现就没法修。我在项目里会专门维护一个error_samples目录把每次线上异常现场完整dump下来。第三板斧写一个最简复现脚本。这个脚本不接业务代码只保留模型调用、数据处理两步专门用来做假设验证。我的项目里一直保留一个benchmark.py所有疑似模型层的问题都先在这个脚本里跑一遍五分钟内就能确认是代码问题还是模型问题。建立这套归因思维之后后面这七种报错就都有清晰的定位坐标了。2. 报错一API Key 无效与限流401/403/429怎么治排在第一位的是每个做AI应用开发的人几乎第一天就会遇到的认证和限流问题。这类报错特征非常鲜明直接抛HTTP状态码401代表认证失败403代表没有权限访问该模型429代表请求太频繁或额度用尽。不同平台报错文本略有差异但本质都一样。2.1 Key 问题的实际排查路径Key出问题的原因比想象中多。最蠢也最常见的是复制Key的时候多带了一个空格或者换行符。用OpenAI的时候报错会明确说Incorrect API key provided国内平台则返回Authentication Fails。你可能会觉得这不可能但实际操作中把Key粘贴到.env文件时行尾残留的换行符就会让HTTP请求头的Authorization变成非法值。我的建议是从第一天起就用环境变量加载Key加载后立刻做一次长度和格式校验import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(DEEPSEEK_API_KEY) if not api_key or len(api_key) 20: raise RuntimeError(API Key 未正确加载请检查 .env 文件)Key放在代码里硬编码是最危险的做法。不只是泄露风险更麻烦的是代码里很容易混入旧Key、测试Key、线上Key排查时根本分不清当前请求用的是哪一个。另外国内模型平台大多兼容OpenAI SDK切换平台只需改base_url和modelfrom openai import OpenAI client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com, ) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 你好}], ) print(resp.choices[0].message.content)这类Key配置错误属于链路层的确定性错误几乎每次都会稳定报错所以排查优先级很高。确认Key没问题之后如果还报403再检查账号是否开通了对应模型的权限。有些新模型需要单独申请白名单没开通时即使Key正确也会被拒绝。2.2 限流对策重试、排队与降级429限流是AI应用开发里最磨人的报错它不像401那样一次性解决而是过一会儿就好但高峰期总来。模型API的限流标准一般有两类每分钟请求数限制、每分钟Token数限制。账号等级越高配额越大但并发一多超限几乎是必然的。处理429有一套成熟的组合拳。第一招是指数退避重试用tenacity库几行代码就能实现from tenacity import ( retry, stop_after_attempt, wait_exponential, retry_if_exception_type, ) import openai retry( retryretry_if_exception_type(openai.RateLimitError), waitwait_exponential(multiplier1, min2, max60), stopstop_after_attempt(6), reraiseTrue, ) def chat_once(messages): resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, ) return resp.choices[0].message.content注意这个wait_exponential是从2秒起步每次翻倍最多60秒最多重试6次。曾经有同事把min设成0.1秒结果重试比不重试更糟——请求排队时间反而拉长了整体延迟。429本身就是服务端在说你慢一点你偏要快速重试那就是火上浇油。第二招是应用层排队。如果你的应用有并发请求不能所有请求都无脑重试而是应该把请求放进队列统一限速。比如运营后台批量调用AI做摘要就应该用信号量控制并发数在2到3个而不是一次发20个请求出去。第三招是降级。这是线上系统能不能保住体验的关键。我的做法是对非核心请求比如聊天开场白里的推荐问题、低优先级的摘要任务连续重试失败后直接返回缓存值或预设的兜底文案而不是让用户看到报错页。对核心请求则在日志里记录失败明细进入补偿队列稍后重跑。2.3 哪些错误值得重试哪些不值得这里要强调一个反直觉的结论不是所有错误都适合重试。很多人给所有AI调用统一加重试结果把4xx业务错误也重试了6遍。4xx错误比如参数格式错误、请求体字段不对重试100次结果一样纯属浪费配额和日志空间。值得重试的只有这几类429限流、5xx服务端错误、连接超时、以及模型服务端返回的临时性错误如503。判断标准其实很简单这个错误是不是过几秒就会自己好。如果是重试有效如果是代码问题或参数问题重试无效。把这两类分开处理系统才不容易在高峰期被自己的重试逻辑拖垮。我见过一个数据同步任务因为给参数错误加了重试本来一次就能发现的错误硬是重试了3小时把日志和费用都刷爆了。3. 报错二上下文窗口超限Token Overflow的三种解法如果说429是进门被拦那Token超限就是屋小装不下。每个大模型都有固定的上下文窗口从几千到几十万Token不等。一旦prompt总长度超过窗口上限服务端直接拒绝请求常见报错是maximum context length is XXX tokens。这个问题在AI应用开发里出现频率极高因为它的根源不是单一代码错误而是系统设计没做好信息管理。只要你搞多轮对话、搞RAG、搞Agent早晚要面对它。3.1 典型报错与出现场景我们项目里第一次大规模踩坑是做多轮对话客服机器人。用户聊了十几轮之后系统突然开始报messages resulted in 12000 tokens, exceeding the models maximum context length。原因很典型——我们把每一轮的用户消息、机器人回复、检索到的知识文档全部原样塞进messages数组一轮轮积累下来自然就爆了。还有几个高频出事场景。RAG应用里检索到的相关文档块一次性全塞进prompt哪怕每块只有500Token20块就是1万Token还没算上对话历史。Agent场景更夸张工具调用的输入输出会被模型当作上下文继续累积一个工具返回一份长日志几个来回就超限了。更隐蔽的是有些人习惯把完整配置文档、Prompt模板、示例全塞进system消息好几KB文字一去不复返留给业务的空间自然就少了。处理Token超限的第一步是能在请求发出之前就知道自己用了多少Token。字符串的len()在中文场景下完全不可靠一个中文字符在有的模型里算1个Token在有的模型里算2个甚至更多英文字符则通常不到1个Token。正经做法是用模型的Tokenizer来数。3.2 先学会数Token再看窗口预算以OpenAI模型为例数Token的标准姿势是import tiktoken enc tiktoken.encoding_for_model(gpt-4o) prompt 你是客服助手请回答用户问题。 token_count len(enc.encode(prompt)) print(token_count)其他模型平台都有自己的Tokenizer库DeepSeek在GitHub上有开源版本也可以直接调平台的Token计数接口。最保险的做法是在封装的调用函数里每次请求前先拼接好完整的messages并统计Token超过阈值就触发截断策略而不是让请求发出去以后被服务端拒绝。我的习惯是给每个模型设定一个安全水位线。比如模型窗口是8K我就把请求Token上限控制在6K留出2K给模型输出。很多报错不是请求本身超出窗口而是请求加上输出一起超了因为模型输出Token也占用窗口空间。这个预算意识很多人会忽略。3.3 滑动窗口与记忆压缩减少历史和压缩记忆Token超限的解决方案核心就两件事减少历史压缩记忆。减少历史最常用的是滑动窗口只保留最近N轮对话比如最近8轮超过8轮的最早消息直接丢弃。这个方案实现简单适合大多数客服、问答场景。但这里有一个坑如果你简单粗暴地截断用户之前提到的关键信息比如我已经下单了会被丢掉导致后面机器人问您下单了吗。所以实际项目里应该加一个关键信息提取层每轮对话后把用户提到的订单号、地址、偏好抽出来存到结构化变量里。对话历史可以丢关键变量不能丢。压缩记忆则是两层的summary方法。每累计若干轮对话就交给模型生成一段摘要之后系统prompt里放的是摘要加最近几轮完整对话。LangChain里的summary buffer memory就是这个思路。用这种方式10轮之前的细节会被压缩成用户反馈过登录问题已确认是验证码延迟既保留语义又省空间。代价是每次压缩额外消耗一次模型调用所以需要设定触发频率不能每轮都压缩。3.4 RAG 场景的分块与召回控制RAG是把外部知识塞给模型的最好方式也是最容易撑爆上下文的元凶。如果你的检索器从向量库里召回了20个片段先别急着全塞给模型先问一句这20个片段真的都有用吗我踩过的坑是关键词命中了文档里好几个不相关内容向量召回又把语义相近但不回答问题的片段也捞了出来全部拼进去之后既浪费Token又引入噪音。正确做法是加一个rerank环节向量库先召回50到100个候选再用rerank模型按相关性排序取前3到5个相关性低于阈值的直接不要。这样既保证回答质量又把Token开销控制在稳定范围。另外分块策略本身也影响Token消耗。分块太大比如整个章节一块检索粒度粗且浪费Token分块太小比如按100字符切又容易切碎语义。我们实践下来500到800字一块、overlap设100到150字对中文文档效果比较平衡关键是在语义完整和块足够小之间找到中间值。4. 报错三JSON 解析失败——模型输出不稳定导致的偶发崩溃AI应用开发里最特色的一种报错就是JSON解析失败。别的报错大多是系统做错了什么这种报错是模型这次没按规矩来。代码写的是json.loads(response)模型却返回了个Markdown代码块包裹的JSON或者直接在JSON末尾多了一句希望这能帮到你你的json.loads当场崩溃。4.1 现场还原与分析真实报错长这样json.JSONDecodeError: Expecting value: line 1 column 1 (char 0)或者在OpenAI SDK里是Failed to parse the JSON response. Please try again.出现原因主要有三个。第一模型默认会在输出里把JSON放在json代码块里而你的代码直接对整体做了json.loads自然解析失败。第二你虽然用了response_format指定返回JSON但模型在输出尾部追加了说明文字这种附带物在严格模式下会导致解析失败。第三输出的JSON里某个字符串值包含换行符或引号模型转义时写错了。很多人第一个反应是换个更强的模型。这能降低概率但无法根治。模型输出的随机性决定了只要不设防这个错误会以一定概率持续出现——哪怕只有1%的概率日活一万的应用一天就是一百次崩溃任何一个用户碰上都是100%的糟糕体验。4.2 结构化输出的两层防线现代模型大多提供了结构化输出能力。在OpenAI系接口里可以用response_format强制返回JSON对象resp client.chat.completions.create( modelgpt-4o, messages[ {role: system, content: 请只输出JSON不要使用Markdown代码块。}, {role: user, content: 把这句话翻译成英文你好}, ], response_format{type: json_object}, ) data json.loads(resp.choices[0].message.content)注意一个细节OpenAI官方文档说用json_object模式时prompt里必须出现json这个单词否则会报错。这是SDK的校验规则不是你想不想写的问题。也有一批平台支持JSON Schema约束相当于给模型一个明确的输出模板把字段名、类型、枚举值全部固定下来生成结果基本不会跑偏。但这只是第一道防线。代码层仍然要兜底因为prompt内容和response_format对输出的控制是尽力而为的不是绝对保证。我在封装层里加了一个safe_parse函数import json import re def safe_parse(text: str) - dict: if not text: raise ValueError(空响应) # 去掉 Markdown 代码块包裹 text re.sub(r^(?:json)?\s*|\s*$, , text.strip()) try: return json.loads(text) except json.JSONDecodeError: # 只取第一个 { 到最后一个 } 之间的内容 start text.find({) end text.rfind(}) if start ! -1 and end ! -1: return json.loads(text[start:end 1]) raise这个函数的思路是先剥离代码块标志如果还失败就尝试提取最外层的JSON片段。它能解决大部分模型输出不干净的问题但遇到JSON里字符串本身包含未转义引号的场景仍然无能为力此时就要走下策修复重试。4.3 解析失败后的自修复机制自修复机制很简单把出错的内容和解析器的错误信息一起打包重新发给模型请它只输出修正后的JSON。实践中我给它设定了最多一次重试因为这种修复成功率高但并非无限次有效。重试超过一次要么是模型彻底糊涂了要么是输出内容本身已经损坏。def repair_json(raw: str, error: str) - dict: fix_prompt ( 下面内容无法被 JSON 解析错误信息是 error 。请只输出修正后的合法 JSON不要任何解释。\n raw ) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: fix_prompt}], response_format{type: json_object}, ) return json.loads(resp.choices[0].message.content)这套强JSON约束 剥壳解析 一次修复重试的三层方案上线后我们项目的JSON解析失败率降到了0.01%以下。没有任何方案能保证100%但做到这个数字线上体验已经几乎无感了。5. 报错四与报错五Function Calling 参数错乱和 Agent 递归死循环Function Calling不少平台叫Tool Calling是Agent开发的核心能力模型不直接回答而是决定调用哪个工具、传什么参数你的代码执行完工具再把结果回填给模型。这个机制爽是真爽坑也是真多。我把两种最典型的报错放在一起讲因为它们经常同时出现参数错乱会导致模型反复试探反复试探又容易演变成死循环。5.1 Schema 定义不一致是头号原因先看两种报错现场。第一种模型依据函数定义返回了一个{name: get_weather, arguments: {city: 北京, date: }}你的函数签名要求两个必填参数date为空直接抛TypeError。第二种模型生成了你根本没定义的函数名返回Function search_user_orders was not found。这些报错的根源绝大多数是函数Schema和实际函数实现不一致。比如你在定义里写了一个参数叫date但Python函数里用的字段叫day模型照着Schema传参执行函数时自然找不到又比如定义里声明某个字段是integer但实现里直接拿它当string用强类型校验时瞬间崩盘。所以第一条铁律函数Schema必须由实际函数签名自动生成不要手写一份给模型看、另一份给自己调用。实践中我推荐pydantic这类库定义好入参模型后Schema由模型自动产出一份传给大模型和实际调用用同一份两边永远不会对不上。5.2 参数强校验错误要回喂给模型即使Schema一致模型仍然可能传错参数。因为大模型在生成arguments时本质是在做文本生成不是真正的类型系统偶尔会把字符串二十传给integer字段或者漏掉可选参数。这个时候不能在工具函数内部裸抛异常否则Agent链路直接中断整个对话体验就是一口黑屏错误。正确做法是在工具入口做强校验校验失败时返回一个结构化的错误信息作为工具执行结果回填给模型让模型基于错误信息自行修正后再调用。听起来有点绕但这是Agent系统工作流的基本设计——模型需要把自己造成的问题重新消化一遍。from pydantic import BaseModel, ValidationError class WeatherArgs(BaseModel): city: str date: str def call_get_weather(raw_args: dict): try: args WeatherArgs(**raw_args) except ValidationError as e: return { status: error, message: f参数不合法{e}。city必须是城市名date必须是YYYY-MM-DD格式。 } return {status: ok, data: query_weather(args.city, args.date)}这里的关键是错误消息要可被模型理解。别只返回Python的ValidationError原始信息那一行Error对模型完全是噪音。你要把修正提示写成人话哪里错了、正确格式是什么。否则模型读不懂只会换个方式继续错。5.3 死循环的终止条件设计比参数错乱更折磨人的是Agent进入死循环。特征模型反复调用同一个工具每次都拿回差不多相同的结果然后再次调用同一个工具直到你的API账单开始报警。我们在做一个数据分析Agent时遇到过模型为了确认本月销售额把sales_summary工具连续调了17次才停下来。死循环的根源不是模型笨而是你的终止条件不够明确。模型是逐轮推理的它没有全局计数器不知道我已经问了18遍同样的问题。所以系统层面必须兜底。我的标准配置是三个参数最大迭代轮数、最大连续相同工具调用次数、单轮工具执行超时。最大迭代轮数一般5到15轮足够超过就强制结束给用户一个我没能完成这个任务请换个说法的兜底回复。连续相同工具调用重复4次就强制打断。单轮工具执行超时设10到20秒防止工具卡死把整个Agent拖住。last_tool, same_count None, 0 for step in range(max_iterations): resp client.chat.completions.create(...) tool_calls resp.choices[0].message.tool_calls if not tool_calls: break tool_name tool_calls[0].function.name if tool_name last_tool: same_count 1 if same_count 4: raise RuntimeError(Agent 陷入重复调用强制终止) else: same_count 1 last_tool tool_name配合前面说的校验失败错误回喂死循环概率能降一个数量级。我见过太多Agent Demo翻车根因就这两个点参数错了直接崩溃或者参数错了但错误信息没回喂模型只能反复试同一招。6. 报错六向量数据库维度不匹配与数据层相关报警做到RAG应用阶段向量数据库就是基础设施。向量库报错里出现频率最高、也最让人疑惑的是维度不匹配。别的报错看关键字能猜个大概这个我第一次遇到时盯着Dimension Mismatch: query dimension 1024 does not match index dimension 768看了半天才反应过来原来是embedding模型换了。6.1 维度不匹配报错还原一个完整的报错链是这样的系统上线时用的sentence-transformers/all-MiniLM-L6-v2生成384维向量建了索引。后来换了bge-large-zh-v1.5生成1024维向量。代码里embedding模型切换了但向量数据库里的collection还是按384维建好的。一检索就报维度不匹配。维度是embedding模型的固有属性不是一个可配置参数。你没法在一个已有索引上升级维度要么把collection删了重建要么新建collection并迁移数据。这个操作在开发环境做起来很简单在生产环境就是一个完整的重建流程涉及数据导出、重新向量化、索引校验、流量切换。6.2 embedding 模型切换的连锁反应很多人以为换embedding模型只是换一个调用接口其实会引发一串连环问题。第一所有已入库的历史数据必须用新模型重新生成向量否则旧向量和新向量的距离计算毫无意义。这一步可能涉及几十万条数据成本和耗时都要提前算账。第二collection的元数据、命名空间、权限配置都要一并迁移。第三也是容易被忽略的不同embedding模型对相似度度量的偏好不同。同一段文本模型A下用余弦相似度效果最好模型B下可能点积更合适。如果你建索引时的metric和检索时的metric不一致哪怕维度相同检索质量也会肉眼可见地下滑。基于这些教训我现在的习惯是embedding模型的版本从第一天起就锁死写进基线文档任何切换都要走评审流程。RAG应用上线前我会写一个sanity check脚本随机抽几十条数据执行查询确认返回结果的召回情况切换模型后先跑一遍这个脚本再放生产。6.3 别让 AI 直接拼 SQLMySQL 1064 的教训数据层报错里另一个高频问题是Text-to-SQL场景下的MySQL 1064语法错误。不少团队想做自然语言查数据库的功能用户问一句LLM生成SQL程序执行。想法很好落地时一堆人在SQL拼接上翻车。1064报错的信息一般是You have an error in your SQL syntax后面跟着一串你根本不认识的SQL片段。最典型的翻车现场是LLM生成的SQL里混入了用户输入的原始值。比如用户名字叫OReilly单引号没有转义拼进WHERE name OReilly直接语法错。又比如LLM脑补了一个不存在的列名把orders写成oders语法对但执行时抛另一个错。更隐蔽的是LLM生成的SQL和生产库的表结构大版本不一致用了已经废弃的字段。我的处理原则很简单不要让LLM生成的SQL直接执行。如果一定要做至少加两层闸门。第一层参数化查询。LLM生成的SQL里的常量值一律用占位符替换再绑定参数彻底避免注入和转义问题。第二层列名和表名白名单校验。执行前先做词法分析把SQL里的表名列名提取出来和数据库schema白名单比对出现白名单之外的标识符直接拒绝执行。import re ALLOWED_COLUMNS {id, name, orders, amount, created_at} def validate_sql_identifiers(sql: str) - bool: identifiers re.findall(r?([a-zA-Z_][a-zA-Z0-9_]*)?, sql) suspicious [i for i in identifiers if i not in ALLOWED_COLUMNS] return len(suspicious) 0这段正则只是示意真正的生产实现应该用SQL解析库做AST级别校验而不是正则。但核心思想必须明确LLM负责生成意图你负责控制执行边界。让AI生成的SQL裸奔到生产数据库上迟早会在线上看到那句让你后背发凉的1064。7. 报错七前端工程集成里的 process is not defined 与 link.exe not foundAI应用不是只有后端接口和大模型通信前端集成环节同样有大量坑。这里挑两个有代表性的Vite项目的process is not defined以及Windows环境下Tauri的link.exe not found。它们虽然不是AI逻辑本身的问题但经常在AI应用上线前最后一个晚上跳出来拦住你。7.1 Vite 中 process is not defined 的根源与修复报错文本是Uncaught ReferenceError: process is not defined通常出现在浏览器控制台。第一眼很意外后端代码里用process.env很常见怎么浏览器里没有原因很简单Vite默认把代码跑在浏览器环境浏览器里没有Node.js的全局对象process。如果你引入的某个第三方包内部写了if (process.env.NODE_ENV production)这种Node风格代码打包到浏览器里一执行就直接报错。解决方案有两个方向。不想动第三方包的话在Vite配置里做define注入// vite.config.js import { defineConfig } from vite export default defineConfig({ define: { process.env.NODE_ENV: JSON.stringify(production), process.env: {}, }, })这个配置的作用是在编译阶段把process.env字样替换成你指定的值。注意不要盲目替换如果你的场景需要读取环境变量浏览器代码里应该用import.meta.env// 浏览器代码里不要用 process.env.XXX // 改成 const apiBase import.meta.env.VITE_API_BASE ?? /api第二个方向是治本找到引入这个依赖的代码换成浏览器兼容的实现。很多Node风格库其实都有浏览器版本只是你import错了入口。这个方案需要业务代码改动但长期收益更高不会反复被第三方包里的Node假设恶心到。7.2 Windows 下 link.exe not found 与 Tauri 编译链做Tauri应用的朋友一定见过这个报错编译时报link.exe not found。Tauri的Rust后端在Windows上默认使用MSVC工具链而MSVC工具链需要Visual Studio Build Tools提供link.exe。很多人装Rust的时候根本没装Build Tools于是第一次编译就卡死。排查顺序很简单。先看当前工具链rustup show如果显示的是stable-x86_64-pc-windows-gnu说明你用GNU工具链而Tauri的依赖对GNU环境支持不好会各种编译失败。需要切到MSVCrustup default stable-x86_64-pc-windows-msvc如果显示已经是MSVC但还报link.exe not found那就是Build Tools没装全。去Visual Studio Installer里装使用C的桌面开发工作负载包含MSVC编译器、Windows SDK等组件装完重启电脑再重新编译。这个小坑一度让我放弃在Windows上玩Tauri后来装完Build Tools半小时就解决了。值得一提的还有如果你用GNU工具链编译时恰好没报错也要小心产物在目标机器上可能因为缺少MSVC运行时而运行异常。所以Windows下坚持MSVC工具链省心得多。7.3 工程报错的通用定位套路工程报错的问题在于它报错的位置往往和真正的原因隔了几层。process is not defined报在业务代码里但根因是某个第三方包用了Node全局变量link.exe not found报在链接阶段但根因是工具链选错了。我总结的通用套路是三看三隔离。三看看报错发生在编译阶段还是运行阶段看报错堆栈的前三条和后三条看当前环境的Node、Rust、编译工具链版本和项目文档要求是否一致。三隔离去掉所有业务代码只留最小样例看能否复现换一台干净机器或CI环境复现把版本锁定文件package-lock.json、Cargo.lock重新生成后再跑一遍。工程报错90%都能靠这三步定位剩下的10%大多是某个依赖包自身的bug这时候果断升级或降级依赖版本不要在一个问题上死磕超过一小时。8. 七种报错速查表与我在项目里的排查习惯到这里七类报错都过了一遍。最后放一张我在项目内部分享会里用过的速查表把每个报错的典型特征和首选行动列出来方便遇到问题时直接对号入座。8.1 七种报错速查表报错类别典型特征首选排查方向防复发方案API认证与限流Invalid API key、Rate Limit、401/403/429Key配置、账号权限、配额用量环境变量管理Key 指数退避重试 缓存降级上下文超限maximum context length is...请求总Token预计算滑动窗口 摘要压缩 RAG分块与rerankJSON解析失败JSONDecodeError、JSON parse error模型原始输出、是否被Markdown包裹结构化输出 剥壳解析 一次修复重试Function Calling参数错乱missing required argument、参数类型错Schema与函数实现一致性Pydantic强校验 错误回喂模型自纠Agent递归死循环同一工具反复调用、Token激增是否有终止条件最大迭代轮数 相同调用次数封顶 工具超时向量维度不匹配Dimension Mismatchembedding模型版本锁版本 重建索引 切换前跑召回验证前端与编译集成process is not defined、link.exe not found运行环境与构建工具链define注入、import.meta.env、MSVC工具链8.2 我长期保留的排查习惯最后一节聊点制度性的习惯。这些习惯不是用来解决某一次报错的而是让报错本身变得更容易被解决。第一所有AI模型调用必须走统一封装层。不要在业务代码里各new一个client而是统一封装处理超时、重试、日志、Token统计。这样排查时只需要看一个入口而不是翻遍几十个调用点。第二日志必须打印prompt快照。AI应用的日志如果只记调用失败事后根本无从分析。我要求团队记录每个请求的模型版本、prompt前200字、原始响应前200字、耗时和错误类型。这五分钟的记录工作能在故障复盘时省下半天。第三给依赖锁版本。模型版本、embedding版本、向量库schema版本、Node版本、Rust工具链版本全部在文档里锁死。AI应用报错很多来自昨天还好好的今天突然崩了而这类问题几乎都是版本漂移引起的。第四不要怕写防御性代码。JSON解析失败的概率再低也要兜底工具调用参数再准也要强校验。AI是概率系统你的代码就必须接受并处理概率性错误。这一点想通了AI应用开发的报错就没有那么吓人了。我在实际项目中最大的体会是报错不可怕可怕的是没有一套稳定的排错顺序。三层归因思维加这张速查表基本能应付90%以上的AI应用开发事故。
1. AI 应用报错的特殊性先建立三层归因思维做AI应用开发这几年我最大的感受是报错从单选题变成了多选题。传统Web开发里报错通常是确定的——数据库连不上就是地址或账号问题语法错误就是代码写法问题搜一下几乎都有标准答案。但AI应用不一样模型输出自带随机性整条链路又特别长前端、后端、模型API、向量库、工具调用、日志系统全串在一起一个异常往往是两三个因素叠加后的结果。同样是API调用超时可能是你的prompt太长导致服务端预处理变慢也可能是模型服务端那一刻负载过高还可能是本地代码库版本太老把重试逻辑拖进了死循环。再比如JSON解析失败可能是你的代码解析逻辑写错了但更常见的是模型这次输出抽风在合法JSON外面裹了一层Markdown代码块。所以我要先给一套排错方法论不要急着搜报错文本先分清楚这个报错来自哪一层。1.1 报错从单选题变成多选题的底层原因报错变复杂底层原因无非三层。第一层是模型层。模型本身是概率输出同样的请求这次给你合法JSON下次就在里面插一句废话这次正常调用下次因为服务端限流返回429。模型层错误的特征是偶发、难以稳定复现重试一次往往就好了但如果不做防护它在线上会以固定概率不断出现日活越大问题越刺眼。第二层是链路层。链路层问题出在你自己的代码和系统设计上结构化输出没开、工具函数参数没校验、RAG分块不合理、向量维度写死、Agent没有终止条件。链路层错误的特征是稳定复现只要把触发条件跑一遍它必然爆。这类问题最折磨人因为责任完全在自己这边模型服务商帮不了你。第三层是工程层。这一层跟AI逻辑没关系纯粹是框架、编译、部署的坑比如Vite项目里报process is not definedWindows上做Tauri打包报link.exe not foundNode版本与构建工具链不匹配。工程层错误的特点是出现时机特别巧往往在你准备上线的前一晚突然冒出来。1.2 三层归因判断法用三个问题锁定方向报错出现时先问自己三个问题。第一个问题能稳定复现吗连续触发三次每次都报同样的错大概率是链路层优先检查自己的代码复现不出来基本就是模型层的随机性或服务端偶发故障。这个判断能直接砍掉一半排查时间。第二个问题报错文本里有没有明确的HTTP状态码或平台错误码比如401、403、429这些状态码直接去查对应平台的API文档不要自己瞎猜。自由格式的文本报错比如JSONDecodeError、Dimension Mismatch多半来自链路层回到代码里找问题。第三个问题如果完全不碰AI的代码纯静态页面或纯后端接口会不会报这个错如果会说明是工程层先解决工程问题再回来调AI逻辑不然很容易在AI代码里浪费大量时间。这三个问题的顺序就是我的标准排错顺序先复现、再归类、最后最小化。最小化复现这一条尤其重要——把请求简化到只有一个system消息、一个user消息去掉工具调用、去掉历史记忆、去掉RAG检索如果报错消失了就一层层加回来加一层测一次很快就能定位到是哪一步引入了问题。1.3 排查前三板斧复现、看原文、留样本说点实际经验。我见过太多同事拿着SDK包装后的异常信息来问问题比如OpenAI库抛了个BadRequestError我该怎么办但我把原始响应打印出来才发现根本问题是prompt超长被服务端拒绝SDK包装后的信息把关键内容吞掉了。所以第一板斧永远先看原始HTTP响应至少要打印response.text或者resp.model_extra别只看SDK转译后的异常。第二板斧每次报错都要保留完整的请求快照包括模型版本、请求参数、原始响应、时间戳。AI应用的报错是概率性的没有快照你根本没法复现没复现就没法修。我在项目里会专门维护一个error_samples目录把每次线上异常现场完整dump下来。第三板斧写一个最简复现脚本。这个脚本不接业务代码只保留模型调用、数据处理两步专门用来做假设验证。我的项目里一直保留一个benchmark.py所有疑似模型层的问题都先在这个脚本里跑一遍五分钟内就能确认是代码问题还是模型问题。建立这套归因思维之后后面这七种报错就都有清晰的定位坐标了。2. 报错一API Key 无效与限流401/403/429怎么治排在第一位的是每个做AI应用开发的人几乎第一天就会遇到的认证和限流问题。这类报错特征非常鲜明直接抛HTTP状态码401代表认证失败403代表没有权限访问该模型429代表请求太频繁或额度用尽。不同平台报错文本略有差异但本质都一样。2.1 Key 问题的实际排查路径Key出问题的原因比想象中多。最蠢也最常见的是复制Key的时候多带了一个空格或者换行符。用OpenAI的时候报错会明确说Incorrect API key provided国内平台则返回Authentication Fails。你可能会觉得这不可能但实际操作中把Key粘贴到.env文件时行尾残留的换行符就会让HTTP请求头的Authorization变成非法值。我的建议是从第一天起就用环境变量加载Key加载后立刻做一次长度和格式校验import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(DEEPSEEK_API_KEY) if not api_key or len(api_key) 20: raise RuntimeError(API Key 未正确加载请检查 .env 文件)Key放在代码里硬编码是最危险的做法。不只是泄露风险更麻烦的是代码里很容易混入旧Key、测试Key、线上Key排查时根本分不清当前请求用的是哪一个。另外国内模型平台大多兼容OpenAI SDK切换平台只需改base_url和modelfrom openai import OpenAI client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com, ) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 你好}], ) print(resp.choices[0].message.content)这类Key配置错误属于链路层的确定性错误几乎每次都会稳定报错所以排查优先级很高。确认Key没问题之后如果还报403再检查账号是否开通了对应模型的权限。有些新模型需要单独申请白名单没开通时即使Key正确也会被拒绝。2.2 限流对策重试、排队与降级429限流是AI应用开发里最磨人的报错它不像401那样一次性解决而是过一会儿就好但高峰期总来。模型API的限流标准一般有两类每分钟请求数限制、每分钟Token数限制。账号等级越高配额越大但并发一多超限几乎是必然的。处理429有一套成熟的组合拳。第一招是指数退避重试用tenacity库几行代码就能实现from tenacity import ( retry, stop_after_attempt, wait_exponential, retry_if_exception_type, ) import openai retry( retryretry_if_exception_type(openai.RateLimitError), waitwait_exponential(multiplier1, min2, max60), stopstop_after_attempt(6), reraiseTrue, ) def chat_once(messages): resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, ) return resp.choices[0].message.content注意这个wait_exponential是从2秒起步每次翻倍最多60秒最多重试6次。曾经有同事把min设成0.1秒结果重试比不重试更糟——请求排队时间反而拉长了整体延迟。429本身就是服务端在说你慢一点你偏要快速重试那就是火上浇油。第二招是应用层排队。如果你的应用有并发请求不能所有请求都无脑重试而是应该把请求放进队列统一限速。比如运营后台批量调用AI做摘要就应该用信号量控制并发数在2到3个而不是一次发20个请求出去。第三招是降级。这是线上系统能不能保住体验的关键。我的做法是对非核心请求比如聊天开场白里的推荐问题、低优先级的摘要任务连续重试失败后直接返回缓存值或预设的兜底文案而不是让用户看到报错页。对核心请求则在日志里记录失败明细进入补偿队列稍后重跑。2.3 哪些错误值得重试哪些不值得这里要强调一个反直觉的结论不是所有错误都适合重试。很多人给所有AI调用统一加重试结果把4xx业务错误也重试了6遍。4xx错误比如参数格式错误、请求体字段不对重试100次结果一样纯属浪费配额和日志空间。值得重试的只有这几类429限流、5xx服务端错误、连接超时、以及模型服务端返回的临时性错误如503。判断标准其实很简单这个错误是不是过几秒就会自己好。如果是重试有效如果是代码问题或参数问题重试无效。把这两类分开处理系统才不容易在高峰期被自己的重试逻辑拖垮。我见过一个数据同步任务因为给参数错误加了重试本来一次就能发现的错误硬是重试了3小时把日志和费用都刷爆了。3. 报错二上下文窗口超限Token Overflow的三种解法如果说429是进门被拦那Token超限就是屋小装不下。每个大模型都有固定的上下文窗口从几千到几十万Token不等。一旦prompt总长度超过窗口上限服务端直接拒绝请求常见报错是maximum context length is XXX tokens。这个问题在AI应用开发里出现频率极高因为它的根源不是单一代码错误而是系统设计没做好信息管理。只要你搞多轮对话、搞RAG、搞Agent早晚要面对它。3.1 典型报错与出现场景我们项目里第一次大规模踩坑是做多轮对话客服机器人。用户聊了十几轮之后系统突然开始报messages resulted in 12000 tokens, exceeding the models maximum context length。原因很典型——我们把每一轮的用户消息、机器人回复、检索到的知识文档全部原样塞进messages数组一轮轮积累下来自然就爆了。还有几个高频出事场景。RAG应用里检索到的相关文档块一次性全塞进prompt哪怕每块只有500Token20块就是1万Token还没算上对话历史。Agent场景更夸张工具调用的输入输出会被模型当作上下文继续累积一个工具返回一份长日志几个来回就超限了。更隐蔽的是有些人习惯把完整配置文档、Prompt模板、示例全塞进system消息好几KB文字一去不复返留给业务的空间自然就少了。处理Token超限的第一步是能在请求发出之前就知道自己用了多少Token。字符串的len()在中文场景下完全不可靠一个中文字符在有的模型里算1个Token在有的模型里算2个甚至更多英文字符则通常不到1个Token。正经做法是用模型的Tokenizer来数。3.2 先学会数Token再看窗口预算以OpenAI模型为例数Token的标准姿势是import tiktoken enc tiktoken.encoding_for_model(gpt-4o) prompt 你是客服助手请回答用户问题。 token_count len(enc.encode(prompt)) print(token_count)其他模型平台都有自己的Tokenizer库DeepSeek在GitHub上有开源版本也可以直接调平台的Token计数接口。最保险的做法是在封装的调用函数里每次请求前先拼接好完整的messages并统计Token超过阈值就触发截断策略而不是让请求发出去以后被服务端拒绝。我的习惯是给每个模型设定一个安全水位线。比如模型窗口是8K我就把请求Token上限控制在6K留出2K给模型输出。很多报错不是请求本身超出窗口而是请求加上输出一起超了因为模型输出Token也占用窗口空间。这个预算意识很多人会忽略。3.3 滑动窗口与记忆压缩减少历史和压缩记忆Token超限的解决方案核心就两件事减少历史压缩记忆。减少历史最常用的是滑动窗口只保留最近N轮对话比如最近8轮超过8轮的最早消息直接丢弃。这个方案实现简单适合大多数客服、问答场景。但这里有一个坑如果你简单粗暴地截断用户之前提到的关键信息比如我已经下单了会被丢掉导致后面机器人问您下单了吗。所以实际项目里应该加一个关键信息提取层每轮对话后把用户提到的订单号、地址、偏好抽出来存到结构化变量里。对话历史可以丢关键变量不能丢。压缩记忆则是两层的summary方法。每累计若干轮对话就交给模型生成一段摘要之后系统prompt里放的是摘要加最近几轮完整对话。LangChain里的summary buffer memory就是这个思路。用这种方式10轮之前的细节会被压缩成用户反馈过登录问题已确认是验证码延迟既保留语义又省空间。代价是每次压缩额外消耗一次模型调用所以需要设定触发频率不能每轮都压缩。3.4 RAG 场景的分块与召回控制RAG是把外部知识塞给模型的最好方式也是最容易撑爆上下文的元凶。如果你的检索器从向量库里召回了20个片段先别急着全塞给模型先问一句这20个片段真的都有用吗我踩过的坑是关键词命中了文档里好几个不相关内容向量召回又把语义相近但不回答问题的片段也捞了出来全部拼进去之后既浪费Token又引入噪音。正确做法是加一个rerank环节向量库先召回50到100个候选再用rerank模型按相关性排序取前3到5个相关性低于阈值的直接不要。这样既保证回答质量又把Token开销控制在稳定范围。另外分块策略本身也影响Token消耗。分块太大比如整个章节一块检索粒度粗且浪费Token分块太小比如按100字符切又容易切碎语义。我们实践下来500到800字一块、overlap设100到150字对中文文档效果比较平衡关键是在语义完整和块足够小之间找到中间值。4. 报错三JSON 解析失败——模型输出不稳定导致的偶发崩溃AI应用开发里最特色的一种报错就是JSON解析失败。别的报错大多是系统做错了什么这种报错是模型这次没按规矩来。代码写的是json.loads(response)模型却返回了个Markdown代码块包裹的JSON或者直接在JSON末尾多了一句希望这能帮到你你的json.loads当场崩溃。4.1 现场还原与分析真实报错长这样json.JSONDecodeError: Expecting value: line 1 column 1 (char 0)或者在OpenAI SDK里是Failed to parse the JSON response. Please try again.出现原因主要有三个。第一模型默认会在输出里把JSON放在json代码块里而你的代码直接对整体做了json.loads自然解析失败。第二你虽然用了response_format指定返回JSON但模型在输出尾部追加了说明文字这种附带物在严格模式下会导致解析失败。第三输出的JSON里某个字符串值包含换行符或引号模型转义时写错了。很多人第一个反应是换个更强的模型。这能降低概率但无法根治。模型输出的随机性决定了只要不设防这个错误会以一定概率持续出现——哪怕只有1%的概率日活一万的应用一天就是一百次崩溃任何一个用户碰上都是100%的糟糕体验。4.2 结构化输出的两层防线现代模型大多提供了结构化输出能力。在OpenAI系接口里可以用response_format强制返回JSON对象resp client.chat.completions.create( modelgpt-4o, messages[ {role: system, content: 请只输出JSON不要使用Markdown代码块。}, {role: user, content: 把这句话翻译成英文你好}, ], response_format{type: json_object}, ) data json.loads(resp.choices[0].message.content)注意一个细节OpenAI官方文档说用json_object模式时prompt里必须出现json这个单词否则会报错。这是SDK的校验规则不是你想不想写的问题。也有一批平台支持JSON Schema约束相当于给模型一个明确的输出模板把字段名、类型、枚举值全部固定下来生成结果基本不会跑偏。但这只是第一道防线。代码层仍然要兜底因为prompt内容和response_format对输出的控制是尽力而为的不是绝对保证。我在封装层里加了一个safe_parse函数import json import re def safe_parse(text: str) - dict: if not text: raise ValueError(空响应) # 去掉 Markdown 代码块包裹 text re.sub(r^(?:json)?\s*|\s*$, , text.strip()) try: return json.loads(text) except json.JSONDecodeError: # 只取第一个 { 到最后一个 } 之间的内容 start text.find({) end text.rfind(}) if start ! -1 and end ! -1: return json.loads(text[start:end 1]) raise这个函数的思路是先剥离代码块标志如果还失败就尝试提取最外层的JSON片段。它能解决大部分模型输出不干净的问题但遇到JSON里字符串本身包含未转义引号的场景仍然无能为力此时就要走下策修复重试。4.3 解析失败后的自修复机制自修复机制很简单把出错的内容和解析器的错误信息一起打包重新发给模型请它只输出修正后的JSON。实践中我给它设定了最多一次重试因为这种修复成功率高但并非无限次有效。重试超过一次要么是模型彻底糊涂了要么是输出内容本身已经损坏。def repair_json(raw: str, error: str) - dict: fix_prompt ( 下面内容无法被 JSON 解析错误信息是 error 。请只输出修正后的合法 JSON不要任何解释。\n raw ) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: fix_prompt}], response_format{type: json_object}, ) return json.loads(resp.choices[0].message.content)这套强JSON约束 剥壳解析 一次修复重试的三层方案上线后我们项目的JSON解析失败率降到了0.01%以下。没有任何方案能保证100%但做到这个数字线上体验已经几乎无感了。5. 报错四与报错五Function Calling 参数错乱和 Agent 递归死循环Function Calling不少平台叫Tool Calling是Agent开发的核心能力模型不直接回答而是决定调用哪个工具、传什么参数你的代码执行完工具再把结果回填给模型。这个机制爽是真爽坑也是真多。我把两种最典型的报错放在一起讲因为它们经常同时出现参数错乱会导致模型反复试探反复试探又容易演变成死循环。5.1 Schema 定义不一致是头号原因先看两种报错现场。第一种模型依据函数定义返回了一个{name: get_weather, arguments: {city: 北京, date: }}你的函数签名要求两个必填参数date为空直接抛TypeError。第二种模型生成了你根本没定义的函数名返回Function search_user_orders was not found。这些报错的根源绝大多数是函数Schema和实际函数实现不一致。比如你在定义里写了一个参数叫date但Python函数里用的字段叫day模型照着Schema传参执行函数时自然找不到又比如定义里声明某个字段是integer但实现里直接拿它当string用强类型校验时瞬间崩盘。所以第一条铁律函数Schema必须由实际函数签名自动生成不要手写一份给模型看、另一份给自己调用。实践中我推荐pydantic这类库定义好入参模型后Schema由模型自动产出一份传给大模型和实际调用用同一份两边永远不会对不上。5.2 参数强校验错误要回喂给模型即使Schema一致模型仍然可能传错参数。因为大模型在生成arguments时本质是在做文本生成不是真正的类型系统偶尔会把字符串二十传给integer字段或者漏掉可选参数。这个时候不能在工具函数内部裸抛异常否则Agent链路直接中断整个对话体验就是一口黑屏错误。正确做法是在工具入口做强校验校验失败时返回一个结构化的错误信息作为工具执行结果回填给模型让模型基于错误信息自行修正后再调用。听起来有点绕但这是Agent系统工作流的基本设计——模型需要把自己造成的问题重新消化一遍。from pydantic import BaseModel, ValidationError class WeatherArgs(BaseModel): city: str date: str def call_get_weather(raw_args: dict): try: args WeatherArgs(**raw_args) except ValidationError as e: return { status: error, message: f参数不合法{e}。city必须是城市名date必须是YYYY-MM-DD格式。 } return {status: ok, data: query_weather(args.city, args.date)}这里的关键是错误消息要可被模型理解。别只返回Python的ValidationError原始信息那一行Error对模型完全是噪音。你要把修正提示写成人话哪里错了、正确格式是什么。否则模型读不懂只会换个方式继续错。5.3 死循环的终止条件设计比参数错乱更折磨人的是Agent进入死循环。特征模型反复调用同一个工具每次都拿回差不多相同的结果然后再次调用同一个工具直到你的API账单开始报警。我们在做一个数据分析Agent时遇到过模型为了确认本月销售额把sales_summary工具连续调了17次才停下来。死循环的根源不是模型笨而是你的终止条件不够明确。模型是逐轮推理的它没有全局计数器不知道我已经问了18遍同样的问题。所以系统层面必须兜底。我的标准配置是三个参数最大迭代轮数、最大连续相同工具调用次数、单轮工具执行超时。最大迭代轮数一般5到15轮足够超过就强制结束给用户一个我没能完成这个任务请换个说法的兜底回复。连续相同工具调用重复4次就强制打断。单轮工具执行超时设10到20秒防止工具卡死把整个Agent拖住。last_tool, same_count None, 0 for step in range(max_iterations): resp client.chat.completions.create(...) tool_calls resp.choices[0].message.tool_calls if not tool_calls: break tool_name tool_calls[0].function.name if tool_name last_tool: same_count 1 if same_count 4: raise RuntimeError(Agent 陷入重复调用强制终止) else: same_count 1 last_tool tool_name配合前面说的校验失败错误回喂死循环概率能降一个数量级。我见过太多Agent Demo翻车根因就这两个点参数错了直接崩溃或者参数错了但错误信息没回喂模型只能反复试同一招。6. 报错六向量数据库维度不匹配与数据层相关报警做到RAG应用阶段向量数据库就是基础设施。向量库报错里出现频率最高、也最让人疑惑的是维度不匹配。别的报错看关键字能猜个大概这个我第一次遇到时盯着Dimension Mismatch: query dimension 1024 does not match index dimension 768看了半天才反应过来原来是embedding模型换了。6.1 维度不匹配报错还原一个完整的报错链是这样的系统上线时用的sentence-transformers/all-MiniLM-L6-v2生成384维向量建了索引。后来换了bge-large-zh-v1.5生成1024维向量。代码里embedding模型切换了但向量数据库里的collection还是按384维建好的。一检索就报维度不匹配。维度是embedding模型的固有属性不是一个可配置参数。你没法在一个已有索引上升级维度要么把collection删了重建要么新建collection并迁移数据。这个操作在开发环境做起来很简单在生产环境就是一个完整的重建流程涉及数据导出、重新向量化、索引校验、流量切换。6.2 embedding 模型切换的连锁反应很多人以为换embedding模型只是换一个调用接口其实会引发一串连环问题。第一所有已入库的历史数据必须用新模型重新生成向量否则旧向量和新向量的距离计算毫无意义。这一步可能涉及几十万条数据成本和耗时都要提前算账。第二collection的元数据、命名空间、权限配置都要一并迁移。第三也是容易被忽略的不同embedding模型对相似度度量的偏好不同。同一段文本模型A下用余弦相似度效果最好模型B下可能点积更合适。如果你建索引时的metric和检索时的metric不一致哪怕维度相同检索质量也会肉眼可见地下滑。基于这些教训我现在的习惯是embedding模型的版本从第一天起就锁死写进基线文档任何切换都要走评审流程。RAG应用上线前我会写一个sanity check脚本随机抽几十条数据执行查询确认返回结果的召回情况切换模型后先跑一遍这个脚本再放生产。6.3 别让 AI 直接拼 SQLMySQL 1064 的教训数据层报错里另一个高频问题是Text-to-SQL场景下的MySQL 1064语法错误。不少团队想做自然语言查数据库的功能用户问一句LLM生成SQL程序执行。想法很好落地时一堆人在SQL拼接上翻车。1064报错的信息一般是You have an error in your SQL syntax后面跟着一串你根本不认识的SQL片段。最典型的翻车现场是LLM生成的SQL里混入了用户输入的原始值。比如用户名字叫OReilly单引号没有转义拼进WHERE name OReilly直接语法错。又比如LLM脑补了一个不存在的列名把orders写成oders语法对但执行时抛另一个错。更隐蔽的是LLM生成的SQL和生产库的表结构大版本不一致用了已经废弃的字段。我的处理原则很简单不要让LLM生成的SQL直接执行。如果一定要做至少加两层闸门。第一层参数化查询。LLM生成的SQL里的常量值一律用占位符替换再绑定参数彻底避免注入和转义问题。第二层列名和表名白名单校验。执行前先做词法分析把SQL里的表名列名提取出来和数据库schema白名单比对出现白名单之外的标识符直接拒绝执行。import re ALLOWED_COLUMNS {id, name, orders, amount, created_at} def validate_sql_identifiers(sql: str) - bool: identifiers re.findall(r?([a-zA-Z_][a-zA-Z0-9_]*)?, sql) suspicious [i for i in identifiers if i not in ALLOWED_COLUMNS] return len(suspicious) 0这段正则只是示意真正的生产实现应该用SQL解析库做AST级别校验而不是正则。但核心思想必须明确LLM负责生成意图你负责控制执行边界。让AI生成的SQL裸奔到生产数据库上迟早会在线上看到那句让你后背发凉的1064。7. 报错七前端工程集成里的 process is not defined 与 link.exe not foundAI应用不是只有后端接口和大模型通信前端集成环节同样有大量坑。这里挑两个有代表性的Vite项目的process is not defined以及Windows环境下Tauri的link.exe not found。它们虽然不是AI逻辑本身的问题但经常在AI应用上线前最后一个晚上跳出来拦住你。7.1 Vite 中 process is not defined 的根源与修复报错文本是Uncaught ReferenceError: process is not defined通常出现在浏览器控制台。第一眼很意外后端代码里用process.env很常见怎么浏览器里没有原因很简单Vite默认把代码跑在浏览器环境浏览器里没有Node.js的全局对象process。如果你引入的某个第三方包内部写了if (process.env.NODE_ENV production)这种Node风格代码打包到浏览器里一执行就直接报错。解决方案有两个方向。不想动第三方包的话在Vite配置里做define注入// vite.config.js import { defineConfig } from vite export default defineConfig({ define: { process.env.NODE_ENV: JSON.stringify(production), process.env: {}, }, })这个配置的作用是在编译阶段把process.env字样替换成你指定的值。注意不要盲目替换如果你的场景需要读取环境变量浏览器代码里应该用import.meta.env// 浏览器代码里不要用 process.env.XXX // 改成 const apiBase import.meta.env.VITE_API_BASE ?? /api第二个方向是治本找到引入这个依赖的代码换成浏览器兼容的实现。很多Node风格库其实都有浏览器版本只是你import错了入口。这个方案需要业务代码改动但长期收益更高不会反复被第三方包里的Node假设恶心到。7.2 Windows 下 link.exe not found 与 Tauri 编译链做Tauri应用的朋友一定见过这个报错编译时报link.exe not found。Tauri的Rust后端在Windows上默认使用MSVC工具链而MSVC工具链需要Visual Studio Build Tools提供link.exe。很多人装Rust的时候根本没装Build Tools于是第一次编译就卡死。排查顺序很简单。先看当前工具链rustup show如果显示的是stable-x86_64-pc-windows-gnu说明你用GNU工具链而Tauri的依赖对GNU环境支持不好会各种编译失败。需要切到MSVCrustup default stable-x86_64-pc-windows-msvc如果显示已经是MSVC但还报link.exe not found那就是Build Tools没装全。去Visual Studio Installer里装使用C的桌面开发工作负载包含MSVC编译器、Windows SDK等组件装完重启电脑再重新编译。这个小坑一度让我放弃在Windows上玩Tauri后来装完Build Tools半小时就解决了。值得一提的还有如果你用GNU工具链编译时恰好没报错也要小心产物在目标机器上可能因为缺少MSVC运行时而运行异常。所以Windows下坚持MSVC工具链省心得多。7.3 工程报错的通用定位套路工程报错的问题在于它报错的位置往往和真正的原因隔了几层。process is not defined报在业务代码里但根因是某个第三方包用了Node全局变量link.exe not found报在链接阶段但根因是工具链选错了。我总结的通用套路是三看三隔离。三看看报错发生在编译阶段还是运行阶段看报错堆栈的前三条和后三条看当前环境的Node、Rust、编译工具链版本和项目文档要求是否一致。三隔离去掉所有业务代码只留最小样例看能否复现换一台干净机器或CI环境复现把版本锁定文件package-lock.json、Cargo.lock重新生成后再跑一遍。工程报错90%都能靠这三步定位剩下的10%大多是某个依赖包自身的bug这时候果断升级或降级依赖版本不要在一个问题上死磕超过一小时。8. 七种报错速查表与我在项目里的排查习惯到这里七类报错都过了一遍。最后放一张我在项目内部分享会里用过的速查表把每个报错的典型特征和首选行动列出来方便遇到问题时直接对号入座。8.1 七种报错速查表报错类别典型特征首选排查方向防复发方案API认证与限流Invalid API key、Rate Limit、401/403/429Key配置、账号权限、配额用量环境变量管理Key 指数退避重试 缓存降级上下文超限maximum context length is...请求总Token预计算滑动窗口 摘要压缩 RAG分块与rerankJSON解析失败JSONDecodeError、JSON parse error模型原始输出、是否被Markdown包裹结构化输出 剥壳解析 一次修复重试Function Calling参数错乱missing required argument、参数类型错Schema与函数实现一致性Pydantic强校验 错误回喂模型自纠Agent递归死循环同一工具反复调用、Token激增是否有终止条件最大迭代轮数 相同调用次数封顶 工具超时向量维度不匹配Dimension Mismatchembedding模型版本锁版本 重建索引 切换前跑召回验证前端与编译集成process is not defined、link.exe not found运行环境与构建工具链define注入、import.meta.env、MSVC工具链8.2 我长期保留的排查习惯最后一节聊点制度性的习惯。这些习惯不是用来解决某一次报错的而是让报错本身变得更容易被解决。第一所有AI模型调用必须走统一封装层。不要在业务代码里各new一个client而是统一封装处理超时、重试、日志、Token统计。这样排查时只需要看一个入口而不是翻遍几十个调用点。第二日志必须打印prompt快照。AI应用的日志如果只记调用失败事后根本无从分析。我要求团队记录每个请求的模型版本、prompt前200字、原始响应前200字、耗时和错误类型。这五分钟的记录工作能在故障复盘时省下半天。第三给依赖锁版本。模型版本、embedding版本、向量库schema版本、Node版本、Rust工具链版本全部在文档里锁死。AI应用报错很多来自昨天还好好的今天突然崩了而这类问题几乎都是版本漂移引起的。第四不要怕写防御性代码。JSON解析失败的概率再低也要兜底工具调用参数再准也要强校验。AI是概率系统你的代码就必须接受并处理概率性错误。这一点想通了AI应用开发的报错就没有那么吓人了。我在实际项目中最大的体会是报错不可怕可怕的是没有一套稳定的排错顺序。三层归因思维加这张速查表基本能应付90%以上的AI应用开发事故。
