这个坑值得记一笔。升级到新版本后，原来调用的 load_qa_chain 报属性不存在，整条问答链路直接跑不起来。
刚开始盯着「自定义提示词模板的输入变量名变了」，折腾了半个多小时，排掉了。
真正麻烦的地方在于，几个原因的现象几乎一样。旧版链式接口被新的组合式写法取代；依赖的三个包版本不一致，混用了新旧 API；回调与流式接口的调用方式变化。
第一件事是改装新版组合写法
chain = prompt | llm | StrOutputParser()随后用检索器直接拼装问答链
chain = create_stuff_documents_chain(llm, prompt) | RunnableLambda(lambda x: x)然后核对模板变量名与检索输出字段
python -c "print(prompt.input_variables)"剩下的就是跑通一条端到端用例
python -c "print(chain.invoke({'context': docs, 'question': q}))"别只看报错消失，验证要多做一步。新写法返回结果与旧版一致，流式输出可用，链路的日志与回调也能正常采集。
大版本升级最好锁死依赖并写一条回归用例，靠人肉改调用点在链路长的时候非常容易漏。监控比日志更早给出信号，事后回看经常能提前半小时发现异常。