用途:当应用希望比原始 JSON 更强的领域类型时使用本技能,用于工具或 LLM 集成。类型化边界应保持显式,使中间件仍看到可预测的 JSON。
主要能力:类型化值编解码器是纯边界转换器,在 NeMo Relay 发事件或运行中间件前把面向应用的值转成 JSON,再转回框架回调或调用方类型。Python 提供 JsonPassthrough、DataclassCodec、PydanticCodec、BestEffortAnyCodec;Node.js 提供 JsonPassthrough 及自定义 Codec<T>。提供方编解码器与类型化值编解码器不同,用于规范化各提供方 LLM 请求与响应,供中间件和订阅者检查消息、工具、模型名、生成参数和响应标注。内置提供方编解码器有 OpenAIChatCodec、OpenAIResponsesCodec、AnthropicMessagesCodec,覆盖 Python、Node.js、Rust。响应编解码器为 LLM 结束事件标注 id、model、message、tool_calls、finish_reason、usage 等字段,但不改写调用方可见响应。请求编解码器在 LLM 请求拦截前运行,encode 会把标注编辑合并回执行拦截与提供方回调前。
使用方式:初次采用优先用纯 JSON;已有稳定领域模型时再使用类型化包装器。仅在没有严格 schema 的边界使用 BestEffortAnyCodec,框架拥有稳定 schema 时优先 dataclass、Pydantic 或显式 Node.js 编解码器。选择与提供方实际载荷形状匹配的编解码器。网关在 Anthropic Messages、OpenAI Chat Completions、OpenAI Responses 生成路由上始终提供匹配的请求编解码器;这些路由上原始 request.content 视为只读,正文编辑通过标注请求返回,头部编辑仍用原始请求。
限制:类型化包装器目前是 Python 和 Node.js 的一等路径,Rust 直接使用 codec trait。中间件仍操作 JSON 而非类型化对象;拦截与护栏在编码后看到 JSON 值。请求/响应转换归属编解码器。内置请求编解码器保证未变更标注的 JSON 值一致性,只补丁变更字段,保留原生表示细节和未知字段。相关技能:nemo-relay-instrument-calls、nemo-relay-plugin-observability、nemo-relay-debug-runtime-integration。