• 简体中文

    • AI 员工问答调试（LangSmith）

    当你需要排查 AI 员工的问答过程，例如想确认模型改写了什么问题、调用了哪些工具、某一步为什么报错，推荐接入 LangSmith 进行链路追踪。

    接入后，系统在处理问答请求时会把执行链路上报到 LangSmith，你可以直接在 LangSmith 后台查看每次问答的详细 Trace。

    使用步骤

    1. 注册 LangSmith 账号

    先前往 LangSmith 官网注册账号，并获取可用的 API Key。

    2. 配置环境变量

    在启动 Data Agent 服务前，配置以下环境变量：

    LANGSMITH_TRACING_V2=true
LANGSMITH_API_KEY=xxxxxxxx
LANGSMITH_PROJECT=yiask

    参数说明：

    变量说明
    LANGSMITH_TRACING_V2开启 LangSmith Trace 上报，固定设置为 true
    LANGSMITH_API_KEY你的 LangSmith API Key
    LANGSMITH_PROJECTLangSmith 中的项目名称，建议按环境区分，例如 yiask-prod、yiask-test

    3. 启动或重启系统

    完成环境变量配置后，重新启动 Data Agent，让配置生效。

    如果你使用的是 Docker Compose，通常可以把变量写入 .env 或 docker-compose.yml 的 environment 中；如果你使用 Kubernetes，建议写入 Secret 或 ConfigMap 再挂载到 Deployment。

    4. 去 LangSmith 查看问答链路

    系统启动后，再次发起 AI 员工问答。随后进入 LangSmith 后台，打开对应的 Project，即可查看该次问答的 Trace 详情。

    重点可以关注：

    • 用户原始问题
    • 模型中间输出
    • 工具调用参数
    • 各步骤返回结果
    • 报错节点与耗时

    适合排查的问题

    LangSmith 特别适合用于排查以下问题：

    • AI 员工为什么把问题改写错了
    • 为什么没有调用预期的工具
    • 工具调用参数是否正确
    • 某一步报错发生在哪个节点
    • 多轮问答中上下文是否被正确带入

    本地日志与落盘位置

    如果暂时没有接入 LangSmith，或者你想直接到服务器上查看日志文件，也可以先从本地落盘位置排查。

    1. 普通 AI 员工的模型请求日志

    普通聊天 Agent 的模型请求调试日志默认不会落盘，只有在启动服务前显式开启下面这个环境变量时才会写文件：

    YIASK_LLM_TRACING=true

    开启后，系统会把发给大模型的消息上下文写入：

    /tmp/yiask/llm_debug_<sessionId>.log

    如果当前请求没有 sessionId，文件名会退化为：

    /tmp/yiask/llm_debug_no-session_<timestamp>.log

    这类文件主要用于查看：

    • 每一轮实际发给模型的 messages
    • 原始消息数量和裁剪后的最终消息数量
    • tool call 之前的上下文是否正确

    需要注意：这份本地日志目前主要记录请求侧内容，不是完整的 request/response 成对 transcript。

    2. DeepAgent 的本地日志目录

    如果当前 AI 员工使用的是 DeepAgent，相关运行目录会写到项目根目录下：

    storage/private/deepagent-workspace/<threadId>/

    其中常见的几个子目录是：

    • workspace/：DeepAgent 生成的工作文件
    • uploads/：本轮对话上传到沙箱的文件
    • logs/：DeepAgent 调试日志

    日志目录示例：

    storage/private/deepagent-workspace/<threadId>/logs

    这里当前主要能看到类似 compression-debug-*.jsonl 的调试文件，适合排查：

    • 为什么回灌给模型的上下文被压缩了
    • 某个工具返回内容被裁剪了多少
    • 历史工具调用参数是否被清洗

    3. Alisa / Logicform 执行日志

    如果你排查的是 askAlisa、图表数据、Logicform 执行结果或权限过滤，不要只看文件系统，还要看数据库表：

    yiask_logicform_execution

    这张表保存的是 Logicform 执行日志，而不是原始模型 HTTP 收发包。通常会记录：

    • 原始问题及中间结构
    • logicform / normed / beforeEnrich
    • 执行结果
    • function logs
    • _logId、执行状态、耗时等调试字段

    聊天窗口里调试按钮展示的大部分 Alisa 调试信息，就是从这类执行日志衍生出来的。

    4. 什么时候优先看哪一种

    • 想看完整问答链路、模型步骤和工具调用顺序时：优先看 LangSmith
    • 想确认服务端到底给模型传了什么消息时：看 /tmp/yiask
    • 想排查 DeepAgent 的上下文压缩、产物文件或沙箱执行过程时：看 storage/private/deepagent-workspace/<threadId>/
    • 想排查图表、Logicform、权限过滤或 askAlisa 结果时：查 yiask_logicform_execution

    建议

    • 生产环境和测试环境建议使用不同的 LANGSMITH_PROJECT
    • 如果是多人协作排查，建议统一项目命名规则，方便筛选 Trace
    • 当 UI 中的信息不足以定位问题时，优先去 LangSmith 看完整链路

    相关文档