本地模型 Web 界面同时服务几个会话时,回调日志一多,没法对账是常事。先别急着改配置,先确认你遇到的问题是不是日志混叠。
先看日志是否交替出现
当本地模型在Web界面中同时服务多个会话时,LangChain的回调日志会混叠在一起,难以区分每条记录属于哪次请求。判断是否需要级联过滤,可以观察日志中是否出现多个链的on_chain_start/on_chain_end事件交错输出,或者相同llm调用片段反复出现但无法关联到独立任务。此时若你还想准确统计每个请求的耗时与调用层级,就应在回调处理器中引入run_id与parent_run_id的父子链路,并在Web界面按顶层run_id筛选日志。
我通常会在本地跑一个包含两次LLM调用的链,然后连发两个请求,看看日志里是不是出现两组一样的on_chain_start和on_llm_start交错。如果只能看到一串run_id,没法对应到具体任务,那就值得做级联过滤。不要一开始就堆日志量,先让每个记录能归属到顶层run_id,之后所有性能数据才有地方挂。
用 run_id 和 parent_run_id 搭出调用树
一种可落地的做法是继承BaseCallbackHandler,在on_chain_start中获取run_id和parent_run_id,把它们记录为结构化字段,比如写入JSONL日志或内存环形缓冲区。随后在Web界面的请求上下文里保存第一次链调用返回的run_id作为顶层标识,前端传入该ID后,后端过滤所有记录,只保留run_id等于该值或parent_run_id链式指向该值的条目。这样做既能还原完整调用树,又能按需要只展示特定层级的子调用,实现级联过滤。
下面这个处理器会把每条回调记录写成 JSONL,同时在第一次链启动时把 run_id 写入 ContextVar。
import json
from contextvars import ContextVar
from langchain_core.callbacks import BaseCallbackHandler
top_run_id_var = ContextVar('top_run_id', default=None)
class JsonlCallbackHandler(BaseCallbackHandler):
def __init__(self, log_path):
self.log_path = log_path
self._fp = open(log_path, 'a')
def _record(self, event_name, run_id, parent_run_id, **kwargs):
top = top_run_id_var.get()
if top is None:
top = run_id
top_run_id_var.set(run_id)
record = {
'event': event_name,
'run_id': run_id,
'parent_run_id': parent_run_id,
'top_run_id': top,
'tags': kwargs.get('tags'),
}
self._fp.write(json.dumps(record, ensure_ascii=False) + '\n')
self._fp.flush()
def on_chain_start(self, serialized, inputs, *, run_id, parent_run_id=None, **kwargs):
if top_run_id_var.get() is None:
top_run_id_var.set(run_id)
self._record('chain_start', run_id, parent_run_id, **kwargs)
def on_chain_end(self, outputs, *, run_id, parent_run_id=None, **kwargs):
self._record('chain_end', run_id, parent_run_id, **kwargs)
def on_llm_start(self, serialized, prompts, *, run_id, parent_run_id=None, **kwargs):
self._record('llm_start', run_id, parent_run_id, **kwargs)
def on_llm_end(self, response, *, run_id, parent_run_id=None, **kwargs):
self._record('llm_end', run_id, parent_run_id, **kwargs)
注意 on_chain_start 先设置顶层 ID,因为 LangChain 调用链总是先触发 chain_start 再触发内部的 llm_start。如果发现某个请求的 top_run_id 没写进去,优先检查 ContextVar 是否在链执行前被重置。
拿到 JSONL 后,可以用下面的函数在内存里过滤出完整调用树:
def filter_by_top_run_id(records, top_run_id):
by_run_id = {r['run_id']: r for r in records}
keep = set()
def is_child_of_top(r):
seen = set()
parent = r.get('parent_run_id')
while parent and parent not in seen:
if parent == top_run_id:
return True
seen.add(parent)
parent = by_run_id.get(parent, {}).get('parent_run_id')
return False
for r in records:
if r['run_id'] == top_run_id or is_child_of_top(r):
keep.add(r['run_id'])
return [r for r in records if r['run_id'] in keep]
如果你只需要按顶层 ID 拉平所有记录,直接 select top_run_id 就行;需要还原层级时再用这个函数把 parent_run_id 关系串起来。
性能追踪要区分同步和异步
要追踪性能,可以在on_llm_start中记录时间戳,在on_llm_end中计算耗时,并连带记录token数量(如果模型返回了用法信息)。但本地模型常常以异步方式运行,此时应使用AsyncCallbackHandler,并在on_llm_start/on_llm_end中同样使用异步方法,否则时间戳会因等待事件循环而产生偏差。更稳妥的做法是只在on_llm_end中记录结束时间,并与on_llm_start的timestamp值求差,同时把耗时字段单独输出,方便后续聚合。
异步处理器示例:
import json
import time
from langchain_core.callbacks import AsyncCallbackHandler
class AsyncTimingHandler(AsyncCallbackHandler):
def __init__(self):
self._starts = {}
async def on_llm_start(self, serialized, prompts, *, run_id, parent_run_id=None, **kwargs):
self._starts[run_id] = time.perf_counter()
async def on_llm_end(self, response, *, run_id, parent_run_id=None, **kwargs):
start = self._starts.pop(run_id, None)
if start is None:
return
duration_ms = (time.perf_counter() - start) * 1000
usage = getattr(response, 'llm_output', {}) or {}
token_count = (usage.get('token_usage') or {}).get('total_tokens', 0)
print(json.dumps({
'run_id': run_id,
'duration_ms': duration_ms,
'total_tokens': token_count,
}, ensure_ascii=False))
注意 on_llm_end 里的 response 类型要结合你用的模型供应商确认,token_usage 字段不一定存在。没有 token 数时,至少把耗时单独记下来,后面按 run_id 聚合。
日志别写 prompt,写文件别拖慢推理
实现日志过滤时,应避免把完整的prompt与生成结果直接写入日志,因为本地模型也可能处理用户隐私数据,且Web界面日志可能被多用户访问。建议只记录输入输出长度、截断后的摘要或hash值。此外,在回调处理器内执行文件写入或网络发送会显著拖慢链的执行速度,尤其是在本地模型推理已经占用高CPU/内存的情况下。应使用异步写入、批量提交,或者设置采样率(例如每10次请求记录一次),并控制日志级别。
如果你用的是上面的同步 JSONL 写法,建议在本地环境先压一次请求,确认文件写入没有成为瓶颈。否则就把 handler 改成批量攒内存,或把记录 push 到异步队列,由专门任务落盘。
回调处理器别抛异常,线程局部存储不可靠
回调处理器里抛异常是个容易翻车的点。LangChain 默认同步调用回调,处理器里任何未被捕获的异常都会向上传播,导致链执行中断。我会在 _record 外再包一层 try/except Exception,只把异常信息打到 stderr,绝不重新抛出。另一个坑是你不能假设处理器运行在 Web 请求线程里。用线程局部存储时,回调可能跑在推理线程,取不到当前请求对象。用 ContextVar 而不是 threading.local,同时确认你的 Web 框架会复制 context 到异步任务里。
改完后看这几个信号
验证前,先手动从日志里筛出顶层请求。如果你写的是 JSONL,可以直接用 jq:
jq 'select(.top_run_id == $top)' `--arg` top "7f3e2b1a-..." app.jsonl
然后发起一个包含多次 LLM 调用或工具调用的测试请求,按返回的顶层 run_id 过滤日志。检查点包括:所有属于该请求的 on_llm_start/on_llm_end 事件是否都被保留,子调用的 parent_run_id 是否都指向当前链路的祖先;同时发起另一个请求,确认两个请求的日志不会互相交叉。若开启了性能追踪,还可以在 Web 界面上按时间轴展示各层调用的耗时,观察是否存在超过预期时长的热点调用。
如果过滤后发现某个请求的顶层 run_id 没被写入,优先查 ContextVar 是否在链执行前被重置。如果调试后仍然对不上,可以在 on_chain_start 里临时打印一次 run_id,确认回调确实被触发。