人工智能大模型AI 安全治理模型安全内容安全提示词注入防护RAG【免费下载链接】GuardrailsNeMo Guardrails is an open-source toolkit for easily adding programmable guardrails to LLM-based conversational systems.项目地址https://gitcode.com/gh_mirrors/ne/Guardrails点击查看免费下载本文以 NeMo Guardrails 的追踪Tracing能力为主线讲解如何启用并接入 Guardrails 交互追踪从而监控哪些护栏被激活、观察 LLM 调用与响应、定位性能瓶颈并还原完整对话流程。读完本文你将掌握config.yml中tracing配置项的完整写法、FileSystem 与 OpenTelemetry 两类适配器的接入方式、自定义适配器的实现方法以及从旧版配置平滑迁移到 OpenTelemetry 最佳实践的路径。一、什么是 Tracing看穿 Guardrails 内部的一次交互追踪Tracing解决的是黑盒问题当一个用户请求进入 Guardrails中间经历了输入护栏检查、LLM 调用、输出护栏校验、流式生成等多个环节最终返回响应。追踪能力让你看清这条链路上发生了什么追踪哪些护栏rail被激活每一次交互实际命中了哪些输入/输出护栏、哪些 flow监控 LLM 调用与响应记录调用耗时、模型名、输入输出内容可选调试性能问题通过 span 的起止时间还原各环节耗时定位慢在护栏还是慢在 LLM分析对话流还原从用户消息到 bot 回复的完整事件序列。从源码结构看追踪的核心链路位于 nemoguardrails/tracing/ 目录Tracer类负责把一次交互InteractionOutput与生成日志GenerationLog转换为InteractionLog再交给配置好的适配器导出span 的抽取逻辑由 span_extractors.py 中的SpanExtractorV1/SpanExtractorV2实现它们根据activated_rails的时间信息构建出 interaction、rail、LLM 调用等 span 树。也就是说一次交互的内部快照最终以InteractionLog为载体包含activated_rails、完整事件列表events和tracespan 集合定义见 interaction_types.py。二、快速开始30 秒跑通一个带追踪的示例1. 安装追踪依赖# 安装追踪支持含 SDK 依赖示例所需 pip install nemoguardrails[tracing] opentelemetry-sdk2. 运行仓库自带的完整示例仓库在 examples/configs/tracing/ 目录下提供了一个开箱即用的可运行示例cd examples/configs/tracing/ python working_example.py运行后追踪结果会立即打印到控制台无需任何外部基础设施。该示例working_example.py的完整流程是setup_opentelemetry()在应用侧配置 OpenTelemetry SDK——创建一个带service.namenemo-guardrails-example、service.version、deployment.environment的Resource注册TracerProvider并挂上ConsoleSpanExporter与BatchSpanProcessorcreate_guardrails_config()用RailsConfig.from_content定义一个问候对话 flow同时通过config{tracing: {enabled: True, adapters: [{name: OpenTelemetry}]}}开启追踪调用rails.generate(...)触发一次真实交互生成并导出 spans最后调用trace.get_tracer_provider().force_flush(1000)强制冲刷剩余的 span。这里有一个关键顺序OpenTelemetry 的 SDK 配置必须发生在 NeMo Guardrails 使用之前因为 Guardrails 只消费已配置好的全局TracerProvider自身不做任何 SDK 初始化。3. 最小配置在 config.yml 中开启追踪在config.yml中启用追踪的最小配置tracing: enabled: true adapters: - name: FileSystem若要改用 OpenTelemetry需要额外在应用代码中做 SDK 配置tracing: enabled: true adapters: - name: OpenTelemetry仓库中现成的示例配置位于 examples/configs/tracing/config.yml它在启用 FileSystem 适配器的同时还指定了输出路径models: - type: main engine: openai model: gpt-3.5-turbo-instruct tracing: enabled: true adapters: - name: FileSystem filepath: ./traces/traces.jsonl三、TracingConfig 配置项全解从源码 nemoguardrails/rails/llm/config.py 可以看到tracing配置由TracingConfig模型承载包含以下字段配置字段默认值说明enabledfalse总开关是否启用追踪。adapters默认一个LogAdapterConfig追踪适配器列表。若未指定使用默认适配器。span_formatopentelemetryspan 格式legacy简单指标格式或opentelemetryOpenTelemetry 语义约定。enable_content_capturefalse是否在追踪/遥测事件中捕获 prompt 与响应user/assistant/tool 消息内容。默认关闭以保护隐私、对齐 OpenTelemetry GenAI 语义约定开启可能把 PII 与敏感数据送入遥测后端需谨慎。关于enable_content_capture的行为差异源码注释有明确说明IORails 引擎环境变量OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT优先级最高true/1强制开启false/0强制关闭其他值回退到本字段OTEL_SEMCONV_STABILITY_OPT_IN决定输出格式包含gen_ai_latest_experimental时输出为 JSON 编码的 span 属性否则输出为逐消息的 span 事件。LLMRails 引擎不读取上述环境变量仅由本字段控制且内容始终通过已废弃的gen_ai.content.prompt/gen_ai.content.completionspan 事件输出。四、内置追踪适配器详解1. FileSystem 适配器最易上手将追踪记录写入本地 JSON 文件JSONL 格式每行一条交互记录适合开发调试tracing: enabled: true adapters: - name: FileSystem filepath: ./logs/traces.jsonl适用场景开发、调试、简单的日志记录需求。从源码 filesystem.py 看该适配器有两个值得注意的实现细节默认路径不传filepath时默认写入./.traces/trace.jsonl传入时会被os.path.abspath转为绝对路径并自动makedirs创建父目录输出结构每条记录是一个 JSON 对象包含schema_version、trace_id即交互 id和spans数组以追加模式a写入文件——同一文件会累积多条交互记录可直接用jq等工具分析。2. OpenTelemetry 适配器tracing: enabled: true adapters: - name: OpenTelemetry适用场景生产环境、对接监控系统、分布式应用。从源码 opentelemetry.py 看OpenTelemetryAdapter严格遵循库只用 API的最佳实践只依赖opentelemetryAPItrace.get_tracer等不修改任何全局状态也不自行创建TracerProvider构造时会检查trace.get_tracer_provider()如果为None或NoOpTracerProvider会发出警告提示应用尚未配置 OpenTelemetryspan 导出时会把InteractionLog中相对起始时间的 span 时间戳换算为绝对纳秒时间base_time_ns取自第一个激活 rail 的started_at回退到time.time_ns()并按span.kind属性把字符串映射为 OpenTelemetry 的SpanKindserver/client/internal事件event的 body 若为字典会被合并进 OTel 事件的 attributes 中因为 OTel 事件只有 attributes 没有独立 body。3. 自定义适配器当内置适配器无法满足需求时可以继承InteractionLogAdapter实现自己的适配器from nemoguardrails.tracing.adapters.base import InteractionLogAdapter class MyCustomAdapter(InteractionLogAdapter): name MyCustomAdapter def transform(self, interaction_log): # 你的自定义逻辑将 InteractionLog 转换为目标后端格式 pass从源码 base.py 看InteractionLogAdapter是一个抽象基类要求实现两个方法同步的transform(interaction_log)与异步的transform_async(interaction_log)后者在Tracer.export_async中通过asyncio.gather并发执行同时提供close()、__aenter__/__aexit__供异步上下文管理使用。此外registry.py 提供了register_log_adapter(model, name)用于注册自定义适配器注册时会校验类必须是InteractionLogAdapter的子类。配置层如何把适配器实例化看 tracer.py 中的create_log_adapters当config.enabled为真时遍历config.adapters从LogAdapterRegistry按name取出适配器类把其余配置项如filepath作为构造参数实例化。五、OpenTelemetry 生态兼容性NeMo Guardrails 与整个 OpenTelemetry 生态兼容。下面的示例只是常见配置实际上任何 OpenTelemetry 兼容组件都可以使用ExportersJaeger、Zipkin、Prometheus、New Relic、Datadog、AWS X-Ray、Google Cloud Trace 等众多导出器CollectorsOpenTelemetry Collector、Jaeger Collector 及自定义 CollectorBackends任何能接收 OpenTelemetry traces 的系统。完整的导出器清单可查阅 OpenTelemetry 官方生态注册表Registry。六、OpenTelemetry 接入架构与安装1. 理解职责分离的架构这是整个接入方案的核心前提NeMo Guardrails只使用 OpenTelemetryAPI不负责任何 SDK 初始化与导出器配置你的应用负责配置 OpenTelemetrySDK与导出器。因此必须在应用代码中完成 OpenTelemetry 的配置Guardrails 才能把 span 送出去。这种设计避免了库与应用的配置冲突也让你自由决定 trace 的去向。2. 按场景安装依赖仅需追踪支持只用 API# NeMo Guardrails 追踪功能的最低要求 pip install nemoguardrails[tracing]这只安装 OpenTelemetry API如果你的应用已经自行配置了 OpenTelemetry这一条就够用。运行示例与开发# 额外包含 OpenTelemetry SDK用于配置导出器 pip install nemoguardrails[tracing] opentelemetry-sdk生产部署# 安装追踪支持 pip install nemoguardrails[tracing] # 安装 SDK 与所需的导出器 # OTLP pip install opentelemetry-sdk opentelemetry-exporter-otlp # 或 Jaeger pip install opentelemetry-sdk opentelemetry-exporter-jaeger # 或 Zipkin pip install opentelemetry-sdk opentelemetry-exporter-zipkin3. 常见配置示例Console 输出开发/测试把 trace 打印到终端适合开发阶段验证from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter from opentelemetry.sdk.resources import Resource # 配置 OpenTelemetry必须在使用 NeMo Guardrails 之前完成 resource Resource.create({ service.name: my-guardrails-app, service.version: 1.0.0, }, schema_urlhttps://opentelemetry.io/schemas/1.26.0) tracer_provider TracerProvider(resourceresource) trace.set_tracer_provider(tracer_provider) # 使用控制台导出器打印到终端 console_exporter ConsoleSpanExporter() span_processor BatchSpanProcessor(console_exporter) tracer_provider.add_span_processor(span_processor) # 再配置 NeMo Guardrails from nemoguardrails import LLMRails, RailsConfig config RailsConfig.from_content( config{ models: [{type: main, engine: openai, model: gpt-3.5-turbo-instruct}], tracing: { enabled: True, adapters: [{name: OpenTelemetry}] } } ) rails LLMRails(config) response rails.generate(messages[{role: user, content: Hello!}])OTLP 导出器生产就绪对接各类可观测性平台# 安装 OTLP 导出器 pip install opentelemetry-exporter-otlpfrom opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter from opentelemetry.sdk.resources import Resource # 配置 OpenTelemetry resource Resource.create({ service.name: my-guardrails-app, service.version: 1.0.0, }, schema_urlhttps://opentelemetry.io/schemas/1.26.0) tracer_provider TracerProvider(resourceresource) trace.set_tracer_provider(tracer_provider) # 配置 OTLP 导出器 otlp_exporter OTLPSpanExporter( endpointhttp://localhost:4317, # 你的 OTLP Collector 端点 insecureTrue ) span_processor BatchSpanProcessor(otlp_exporter) tracer_provider.add_span_processor(span_processor) # 与 NeMo Guardrails 配合使用时与 Console 示例完全相同注意这些示例是常见配置OpenTelemetry 支持远更多的导出器与后端。安装对应的导出器包并在应用代码中配置后即可接入任何 OpenTelemetry 兼容的可观测性平台。七、更多集成示例1. Zipkin 集成# 1. 启动 Zipkin 服务 docker run -d -p 9411:9411 openzipkin/zipkin # 2. 安装 Zipkin 导出器 pip install opentelemetry-exporter-zipkin# 3. 在应用中配置 from opentelemetry.exporter.zipkin.proto.http import ZipkinExporter zipkin_exporter ZipkinExporter( endpointhttp://localhost:9411/api/v2/spans, ) span_processor BatchSpanProcessor(zipkin_exporter) tracer_provider.add_span_processor(span_processor)2. OpenTelemetry Collector创建一个 Collector 配置文件# otel-config.yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: exporters: logging: loglevel: debug service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [logging]运行 Collectordocker run -p 4317:4317 -p 4318:4318 \ -v $(pwd)/otel-config.yaml:/etc/otel-collector-config.yaml \ otel/opentelemetry-collector:latest \ --config/etc/otel-collector-config.yaml八、从旧版本配置迁移1. 旧的 OpenTelemetry 配置不再受支持❌ 不再支持旧写法tracing: enabled: true adapters: - name: OpenTelemetry service_name: my-service exporter: console resource_attributes: env: production✅ 受支持新写法在应用代码中配置 OpenTelemetrytracing配置只负责开启 指定适配器# 在应用代码中配置 OpenTelemetry from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter tracer_provider TracerProvider() trace.set_tracer_provider(tracer_provider) console_exporter ConsoleSpanExporter() span_processor BatchSpanProcessor(console_exporter) tracer_provider.add_span_processor(span_processor) config RailsConfig.from_content( config{ tracing: { enabled: True, adapters: [{name: OpenTelemetry}] } } )2. 已弃用的register_otel_exporter函数register_otel_exporter函数已弃用将在 0.16.0 版本移除# DEPRECATED - 将在 0.16.0 移除 from nemoguardrails.tracing.adapters.opentelemetry import register_otel_exporter from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter register_otel_exporter(my-otlp, OTLPSpanExporter)应改为直接在应用代码中配置导出器from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter tracer_provider TracerProvider() trace.set_tracer_provider(tracer_provider) otlp_exporter OTLPSpanExporter(endpointhttp://localhost:4318) span_processor BatchSpanProcessor(otlp_exporter) tracer_provider.add_span_processor(span_processor)3. 为什么这样变更这一变更遵循 OpenTelemetry 官方对库与应用的职责划分最佳实践库只使用 API避免配置冲突Guardrails 不触碰 SDK 的任何全局状态应用掌控可观测性由你决定 trace 发往哪里、用什么导出器、带什么资源属性更好的兼容性可与任何 OpenTelemetry 配置协同工作不受内置导出器限制。从源码 opentelemetry.py 的类注释同样能印证这一点该适配器只使用 OpenTelemetry API 并依赖应用配置 SDK不修改全局状态也不创建自己的 tracer provider。九、故障排查常见问题没有出现任何 trace确认 OpenTelemetry 是在应用代码中配置的仅配置 NeMo Guardrails 的tracing是不够的先用ConsoleSpanExporter验证导出器本身工作正常检查config.yml中tracing.enabled是否为true。OTLP 连接错误WARNING: Transient error StatusCode.UNAVAILABLE encountered while exporting traces to localhost:4317确认 Collector/端点服务正在运行测试阶段可以不依赖外部服务直接改用ConsoleSpanExporter。导入错误ImportError: No module named opentelemetry安装追踪依赖pip install nemoguardrails[tracing]使用导出器还需pip install opentelemetry-exporter-otlp等对应包。trace 中的服务名错误在应用代码中通过Resource配置SERVICE_NAME即service.name资源属性旧的service_name参数已不再生效。十、深入源码一次交互的追踪数据流结合仓库源码可以把追踪的数据流完整串联起来对应文件均在 nemoguardrails/tracing/配置解析RailsConfig中的tracing字段被解析为TracingConfigconfig.py适配器实例化create_log_adapters遍历适配器配置经LogAdapterRegistry查表并实例化tracer.py交互日志生成Tracer.generate_interaction_log调用extract_interaction_log把GenerationLog中的内部事件交给SpanExtractorV1/V2抽取 span得到InteractionLoginteraction_types.py导出Tracer.export/export_async依次调用每个适配器的transform/transform_async完成落盘、OTel span 创建或自定义处理。其中 span 的语义属性抽取由 span_formatting.py 的extract_span_attributes、format_span_for_filesystem等函数完成时间基准取自第一个激活 rail 的started_at其余 span 的时间均为相对偏移再由 OpenTelemetry 适配器换算为绝对纳秒时间戳。十一、结语NeMo Guardrails 的追踪体系遵循库只用 API、应用控制导出的 OpenTelemetry 最佳实践配合 FileSystem 适配器可以零依赖地在开发阶段快速看到完整的交互内部视图接入生产环境时只需在应用侧配置好 OTLP/Jaeger/Zipkin 等导出器即可让 Guardrails 交互数据融入你已有的可观测性体系。建议从仓库自带的 working_example.py 与 config.yml 起步先用 Console 输出验证链路再逐步替换为生产级导出器。赞分享人工智能大模型AI 安全治理模型安全内容安全提示词注入防护RAG【免费下载链接】GuardrailsNeMo Guardrails is an open-source toolkit for easily adding programmable guardrails to LLM-based conversational systems.项目地址https://gitcode.com/gh_mirrors/ne/Guardrails点击查看免费下载相关推荐Megatron-LM 可观测性实战指南基于 OpenTelemetry 与 nemo-lens 的 Traces、Metrics 与 Pipeline 并行追踪Megatron LM 可观测性实战指南基于 OpenTelemetry 与 nemo lens 的 Traces、Metrics 与 Pipeline 并行人工智能大模型预训练分布式训练深度学习强化学习NocoBase 无代码平台开发环境从零跑通5 分钟起本地服务避开 3 个高频坑NocoBase 无代码平台开发环境从零跑通5 分钟起本地服务避开 3 个高频坑 第一次在本地跑 yarn dev 时终端抛出一句 EADDRINUSE低代码后端前端人工智能AI 应用工作流自动化OGX 可观测性实战基于 OpenTelemetry 的指标、链路追踪与仪表盘体系OGX 可观测性实战基于 OpenTelemetry 的指标、链路追踪与仪表盘体系 导读本文以 OGXOpen GenAI Stack内置的 OpenTAI应用API网关后端模型推理服务上一篇devtools R包终极安装配置指南快速上手完整教程下一篇Apache Spark MLlib 分类与回归算法完全指南从逻辑回归到树集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考