OpenTelemetry Instrumentation for VoyageAI：为 Embedding 与 Rerank 调用接入可观测性

LLMOps可观测性【免费下载链接】openllmetryOpen-source observability for your GenAI or LLM application, based on OpenTelemetry项目地址https://gitcode.com/gh_mirrors/op/openllmetry点击查看免费下载这篇技术指南以 openllmetry 仓库中的 opentelemetry-instrumentation-voyageai 文档为主体讲解如何通过 OpenTelemetry 对 Voyage AI 的 Embedding文本向量化与 Rerank重排序API 调用进行自动埋点追踪。读完本文你将掌握该插件的安装方式、VoyageAIInstrumentor的启用方法、底层埋点机制与完整的 GenAI 语义约定Semantic Conventions属性清单并学会结合源码与测试用例排查、验证追踪数据。一、插件概览为 Voyage AI 客户端自动生成 Spanopentelemetry-instrumentation-voyageai是一个基于 OpenTelemetry 的自动埋点库用于追踪 Voyage AI Python 客户端发出的 Embedding 与 Rerank 请求。启用后无需修改任何业务代码插件会通过wrapt的wrap_function_wrapper包装客户端方法在每次 API 调用前后自动创建、填充并结束 Span从而将模型名、Token 用量、嵌入向量维度、输入文本等关键信息记录到链路中。从 入口模块 的源码可见插件包装的调用点共有四个客户端对象方法Span 名称gen_ai.operation.namevoyageai.Clientembedvoyageai.embedembeddingsvoyageai.Clientrerankvoyageai.rerankrerankvoyageai.AsyncClientembedvoyageai.embedembeddingsvoyageai.AsyncClientrerankvoyageai.rerankrerank同步与异步客户端被同等对待Span 的kind统一为SpanKind.CLIENTgen_ai.system固定为voyageai。二、安装与启用1. 安装pip install opentelemetry-instrumentation-voyageai该插件的运行环境要求来自 pyproject.tomlPython3.10,4opentelemetry-api1.38.0,2opentelemetry-instrumentation0.59b0opentelemetry-semantic-conventions-ai0.5.1,0.6.0目标库voyageai0.3.0见源码中的_instruments声明插件同时注册了opentelemetry_instrumentor入口点指向VoyageAIInstrumentor因此在配置好 OpenTelemetry 环境后也可以借助opentelemetry-instrument命令行工具自动启用。2. 初始化仪表化from opentelemetry.instrumentation.voyageai import VoyageAIInstrumentor VoyageAIInstrumentor().instrument()instrument()默认使用全局TracerProvider。若应用采用了自定义 Provider可显式传入VoyageAIInstrumentor().instrument(tracer_providermy_tracer_provider)这与测试用例中的做法一致见 conftest.py测试通过VoyageAIInstrumentor().instrument(tracer_providertracer_provider)注入内存 Span Exporter 并断言输出。三、快速上手Embedding 与 Rerank 追踪启用仪表化后按常规方式使用 Voyage AI SDK 即可自动产生 Span。以下代码来自 README 原示例补充了 API Key 与参数说明from opentelemetry.instrumentation.voyageai import VoyageAIInstrumentor VoyageAIInstrumentor().instrument() # 仪表化之后正常使用 Voyage AI SDK 即可 import voyageai client voyageai.Client(api_keyyour-voyage-api-key) # Embeddings文本向量化 result client.embed(texts[Hello, world!], modelvoyage-3) # Reranking按相关性对文档重排序 result client.rerank( queryWhat is the capital of France?, documents[Paris is the capital of France., London is in England.], modelrerank-2.5, )在启用后每次embed/rerank调用都会生成一个 Span采集请求模型、Token 用量等属性详见下一节。仓库中的示例应用给出了更贴近生产的使用形态在workflow装饰的工作流中批量生成 Embedding、执行 Rerank并打印向量维度与 Token 用量可作为搭建完整可观测性链路的参考。四、Semantic Conventions完整属性清单与实现细节插件遵循 OpenTelemetry GenAI 语义约定opentelemetry-semantic-conventions-ai包即 opentelemetry-semantic-conventions-ai 所定义的规范以gen_ai.*前缀的属性记录调用信息。README 声明的基础属性如下属性含义取值/来源gen_ai.systemAI 系统标识固定为voyageaigen_ai.operation.name操作类型embeddings或rerankgen_ai.request.model请求模型名来自kwargs.get(model)gen_ai.usage.input_tokens输入 Token 数来自响应对象的total_tokens属性gen_ai.embeddings.dimension.count嵌入向量维度仅 embed取响应中第一个向量的长度除上述基础属性外从 span_utils.py 的源码还可以确认两个由该插件扩展补充的属性gen_ai.request.top_k仅 Rerank 请求且仅在调用时显式传入了top_k才会写入见 span_utils.pygen_ai.completion.{i}.role/gen_ai.completion.{i}.contentRerank 响应中的每条结果内容格式为Doc {index}, Score: {relevance_score}若结果对象带document字段则追加原文。1. 请求属性如何写入在 span_utils.py 中set_span_request_attributes负责读取调用参数_set_span_attribute(span, GenAIAttributes.GEN_AI_REQUEST_MODEL, kwargs.get(model)) if kwargs.get(top_k): _set_span_attribute(span, GenAIAttributes.GEN_AI_REQUEST_TOP_K, kwargs.get(top_k))_set_span_attribute会忽略None与空字符串确保没有多余的空属性污染 Span。2. 响应属性如何写入set_span_response_attributesspan_utils.py直接从响应对象读取数据total_tokens是 Voyage AI SDK 返回对象的直接属性写入gen_ai.usage.input_tokens对于 Embedding取response.embeddings中第一个向量的长度作为gen_ai.embeddings.dimension.count。之所以采用getattr(response, ...)的读取方式是因为 Voyage AI 的响应是 Pydantic 模型对象而非字典直接属性访问是最稳妥的取值路径。五、输入与输出内容捕获prompts 与 completions当需要追溯到底发送了什么文本、模型返回了什么时插件支持把输入输出内容记录到 Span 中。该能力受环境变量TRACELOOP_TRACE_CONTENT控制默认true即开启判断逻辑位于 utils.pydef should_send_prompts(): return ( os.getenv(TRACELOOP_TRACE_CONTENT) or true ).lower() true or context_api.get_value(override_enable_content_tracing)若要关闭内容采集例如出于隐私或成本考虑可在启动应用前设置export TRACELOOP_TRACE_CONTENTfalse内容捕获遵循以gen_ai.prompt.{i}.role/content记录输入、以gen_ai.completion.{i}.role/content记录输出的约定见 span_utils.pyEmbedding 输入所有texts作为一条user消息content为 JSON 数组[{type: text, text: ...}, ...]Rerank 输入每个documents元素作为一条system消息下标从 0 开始query作为最后一条user消息Rerank 输出每条结果写入gen_ai.completion.{i}roleassistant。需要说明的是内容属性写入有前置条件should_send_prompts()为真且未启用事件模式should_emit_events()即仍使用 legacy 属性时详见下一节配置说明。从源码结构看这一设计是为了兼容旧版属性命名同时为未来基于事件Event的日志模式预留切换空间。六、可配置项exception_logger 与 use_legacy_attributesVoyageAIInstrumentor构造函数接受两个可选参数见init.py 与 config.py参数默认值作用exception_loggerNone自定义异常记录回调。埋点内部异常如属性序列化失败发生时会被调用便于统一上报use_legacy_attributesTrue是否使用 legacy 属性模式。为False时should_emit_events()返回True内容捕获转而走事件路径此时 prompt 内容不再写入 Span 属性示例VoyageAIInstrumentor( exception_loggerlambda e: print(ftracing error: {e}), use_legacy_attributesFalse, ).instrument()七、错误处理与抑制机制1. 调用失败的 Span 状态在 _wrap/_awrap 中插件将业务调用包裹在try/except中调用成功写入响应属性、正常span.end()调用抛错设置StatusCode.ERROR状态、调用span.record_exception(e)记录异常堆栈span.end()后重新抛出异常——即追踪逻辑绝不吞掉业务异常对应用行为零影响。2. 双重抑制开关如果上下文中存在 OpenTelemetry 的_SUPPRESS_INSTRUMENTATION_KEY或语义约定包提供的SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY插件会直接跳过埋点、原样调用见init.py。这意味着你可以通过 Context 在局部关闭追踪例如避免对内部重试或测试流量产生重复 Span。3. 属性采集失败不影响主流程所有属性填充函数都经过dont_throw装饰utils.py即使响应对象结构异常导致属性提取失败也只会记录 debug 日志并调用exception_logger而不会中断埋点或业务调用。八、测试验证如何确认追踪输出符合预期该插件在 tests 目录下提供了基于pytest-recordingVCR的用例使用预录的cassettestest_embed、test_rerank离线重放 API 响应无需真实调用 Voyage AI 即可验证test_embed.py断言embedSpan 的名称、gen_ai.system、gen_ai.operation.name、模型名、prompt 内容 JSON 结构、Token 用量、向量维度以及同步/异步AsyncClient两条路径test_rerank.py断言rerankSpan 中 documents 以system角色、query 以user角色写入以及每条结果以gen_ai.completion.{i}assistant角色记录Doc ... Score: ...格式的内容。测试夹具 conftest.py 展示了标准的验证链路InMemorySpanExporter→SimpleSpanProcessor→ 注入自定义TracerProvider→ 调用instrument(tracer_provider...)→ 用span_exporter.get_finished_spans()断言。如果你要在自己的应用中做集成验证完全可以复用这套模式把 Exporter 换成 OTLP/Console Exporter即可在 Jaeger、Tempo、Grafana Cloud 或 Traceloop 等后端中看到voyageai.embed/voyageai.rerank链路。九、小结与延伸阅读一句话总结opentelemetry-instrumentation-voyageai用最小的侵入代价一行instrument()为 Voyage AI 的 Embedding 与 Rerank 调用补齐了标准化的 GenAI 可观测数据覆盖模型、Token、向量维度、请求/响应内容与异常信息。若需继续深入可参阅仓库内相关资源插件主文档packages/opentelemetry-instrumentation-voyageai/README.md埋点实现opentelemetry/instrumentation/voyageai/init.py属性填充与内容捕获opentelemetry/instrumentation/voyageai/span_utils.pyGenAI 语义约定定义opentelemetry-semantic-conventions-ai端到端示例sample_app/voyageai_example.py赞分享LLMOps可观测性【免费下载链接】openllmetryOpen-source observability for your GenAI or LLM application, based on OpenTelemetry项目地址https://gitcode.com/gh_mirrors/op/openllmetry点击查看免费下载相关推荐用 OpenTelemetry 为 Go 的 GORM 数据库接入可观测性Trace 与 Metrics 实战指南用 OpenTelemetry 为 Go 的 GORM 数据库接入可观测性Trace 与 Metrics 实战指南 本文基于 highlight.io 开源仓人工智能大模型预训练NLPCrawlee 可观测性指南使用 crawlee/otel 为爬虫接入 OpenTelemetry 追踪与日志Crawlee 可观测性指南使用 crawlee/otel 为爬虫接入 OpenTelemetry 追踪与日志 crawlee/otel 是 Crawle后端网页爬虫Haystack 接入 vLLM 完整指南Embedding、Chat、Rerank 与工具调用实战Haystack 接入 vLLM 完整指南Embedding、Chat、Rerank 与工具调用实战 本指南基于开源 AI 编排框架 Haystack 的 v人工智能大模型RAGAI AgentNLP创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考