nemo-relay-debug-runtime-integration

调试运行时集成

当应用中已接入 NeMo Relay，但某些功能无法正常工作时，请使用此技能。 更改配置前，先确认哪个运行时层出现了故障。

首要检查项

• 绑定或原生构件能否加载？
• 执行故障调用时是否存在活动作用域？
• 工作是否在预期的作用域栈上执行？
• 订阅器／导出器／插件配置是否已实际生效？
• 应用是否选择了正确的公共 API 层：托管执行、手动生命周期、类型化包装器，还是自适应组件／插件？

常见故障类别

• Python 原生扩展缺失
• Go 动态库不在加载器路径中
• Node 原生插件未构建或无法加载
• 在作用域外调用执行方法
• 注册从未发生，导致事件缺失
• 并发导致活动作用域栈错误
• 自适应组件从未初始化，或配置验证被忽略

内嵌故障排查矩阵

• Rust 构建失败：先运行范围最小的核心构建，再扩展到受影响的绑定或工作区命令。
• Python 导入失败：使用 uv sync 重建虚拟环境和原生扩展，然后在与应用相同的环境中运行简短的 Python 测试或导入检查。
• Node.js 插件失败：在调试应用代码之前，先从 Node 绑定包重新安装并构建原生插件。
• Go 加载器失败：构建发布版 FFI 共享库，并将链接器和运行时加载器都指向发布输出目录；在 macOS 上使用动态库路径变量（DYLD_LIBRARY_PATH）。
• 作用域栈为空：工作处于活动作用域之外，或跨越了线程、任务、goroutine 或 worker 边界，但未携带预期的栈。
• 工作泄漏到其他请求：多个独立请求共用了一个作用域栈；请为每个独立请求或 Agent 创建新的栈。
• 中间件缺失或顺序错误：检查全局与作用域局部注册、活动作用域的祖先关系、名称和优先级值。
• 订阅器缺少事件：在事件发出前完成注册；对于作用域局部订阅器，请确保当前作用域是所有者或其后代。
• 事件字段缺失：托管辅助方法会填充语义字段；手动生命周期调用需要为输入、输出、模型名称和工具调用 ID 显式提供参数。
• ATIF 为空或内容混杂：在工作开始前完成注册；每次运行使用一个导出器，或在不同运行之间清空；通过根作用域隔离并发 Agent。
• 提供方负载转换失败：使用显式编解码器转换非 JSON 提供方对象、SDK 句柄、回调、流或类实例。
• 插件验证失败：将配置验证与运行时注册分开，并检查必填字段、值类型、默认值和配置来源。
• 自适应行为未改变：确认插桩会发出事件、自适应组件已启用、策略允许此行为，并且调用路径能够到达已配置的组件。
• OpenTelemetry 或 OpenInference 导出失败：首先确认 Relay 版本。对于 0.6，检查单独的导出器、http_binary 与 grpc、端点、标头、目标支持情况，以及原生 gRPC 所需的活动 Tokio 运行时。对于 0.7，检查类型化投影、端点、标头、TLS 和目标支持情况；原生 gRPC 运行时由订阅器负责管理。
• 回调成功但未出现生命周期事件：确认集成使用了托管执行辅助方法或成对的手动开始／结束 API，而不只是底层业务回调。

相关技能

• nemo-relay-get-started
• nemo-relay-instrument-context-isolation
• nemo-relay-plugin-adaptive-tuning
• nemo-relay-plugin-build