| 名称 | nemo-relay-instrument-typed-wrappers |
| 描述 | 当添加NeMo Relay类型化包装器、域类型或提供者编解码器，同时希望保留JSON中间件语义和调用方可见行为时，请使用此技能。 |
| 开源协议 | Apache-2.0 metadata: |
| 作者 | NVIDIA Corporation and Affiliates |
使用类型化包装器和编解码器
当应用程序需要比原始JSON更强的领域类型用于工具或LLM集成时，请使用此技能。 保持类型化边界明确，以便中间件仍然能够看到可预测的JSON。
默认指南
- 初始采用优先使用纯JSON。
- 当应用程序已有稳定的领域模型时，再使用类型化包装器。
- 请记住，中间件仍然基于JSON操作，而不是类型化对象。
嵌入式编解码器模型
- 类型化值编解码器是一种纯粹的边界转换器。它在NeMo Relay发出事件或运行中间件之前，将面向应用程序的值转换为JSON，然后在框架回调或调用方类型中再将JSON转换回来。
- Python提供
JsonPassthrough、DataclassCodec、PydanticCodec和BestEffortAnyCodec。Node.js提供JsonPassthrough以及自定义的Codec<T>实现。 - 仅在缺少严格模式时在边界使用
BestEffortAnyCodec。当框架拥有稳定模式时，优先使用dataclass、Pydantic或显式的Node.js编解码器。 - 提供者编解码器不同于类型化值编解码器：它们规范化特定于提供者的LLM请求和响应，以便中间件和订阅者能够检查消息、工具、模型名称、生成参数和响应注解。
- 内置的提供者编解码器包括Python、Node.js和Rust中的
OpenAIChatCodec、OpenAIResponsesCodec和AnthropicMessagesCodec。选择与实际提供者负载形状匹配的编解码器。 - 响应编解码器使用
id、model、message、tool_calls、finish_reason、usage、特定于提供者的数据以及额外未建模字段等注解LLM结束事件。它们不会重写调用方可见的响应。 - 请求编解码器在LLM请求拦截之前运行。拦截同时接收原始
LLMRequest和可选的注解请求；encode在执行拦截和提供者回调运行之前合并注解编辑。
关键规则
- 类型化包装器目前是Python和Node.js的一等路径；Rust直接使用编解码器特性
- 请求/响应转换属于编解码器
- 拦截和护栏在编码后看到JSON值
- 中间件所做的更改会保留到解码步骤
选择编解码器
JsonPassthrough用于JSON原生值- 当模型已存在时，在Python中使用
DataclassCodec或PydanticCodec - 自定义编解码器用于特定领域的线格式
BestEffortAnyCodec仅在广泛灵活性值得更宽松的契约时使用- 提供者编解码器用于LLM提供者负载，而不是应用程序域对象转换
验证清单
- [ ] 编解码器输出与JSON兼容
- [ ] 必填字段在
toJson/fromJson或decode/encode中保留 - [ ] 中间件看到预期的序列化形状
- [ ] 提供者编解码器保留它们不理解的字段
- [ ] 响应编解码器故障不会破坏底层的LLM调用
- [ ] 请求编解码器
encode保留原始提供者字段，除非拦截有意更改它们
相关技能
nemo-relay-instrument-callsnemo-relay-plugin-observabilitynemo-relay-debug-runtime-integration