Phoenix OTEL 文档站构建指南：Sphinx 本地构建、Read the Docs 部署与 API 文档维护

可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载本篇指南系统讲解 Phoenix 项目中arize-phoenix-otel包官方文档站Sphinx 文档的构建、结构、自动部署与维护更新全流程你将掌握在本地把文档从源码构建为可浏览 HTML 的完整命令链理解conf.py中 autodoc、MyST、版本切换等关键配置的用途并学会如何为新增模块维护 API 参考页面。同时指南会结合phoenix/otel的源码实现带你看清这套文档站实际描述的核心 APIregister()、TracerProvider、Span Processors、Exporters以及它们背后的 Phoenix 感知默认值逻辑。一、这套文档站描述的是什么arize-phoenix-otel 概览文档站的核心目录是 packages/phoenix-otel/docs/它为arize-phoenix-otel包提供 Sphinx 参考文档。根据文档主页 source/index.md 的介绍该包是 OpenTelemetry 原语之上的一层轻量封装为 Phoenix 用户提供常用 OpenTelemetry 原语的Phoenix 感知默认值Phoenix-aware defaults从环境变量进行的自动配置对 OTel 类的即插即用替代实现drop-in replacements并附带增强功能通过register()函数实现的简化追踪设置针对常见 GenAI 模式的追踪装饰器。文档站将包的五个核心组成部分作为 API 参考页面的主线文档页API 参考对应模块组件作用api/register.rstphoenix.otel.register一站式注册与配置入口api/provider.rstTracerProvider、ResourcePhoenix 感知的 TracerProvider 与资源属性api/processors.rstSimpleSpanProcessor、BatchSpanProcessor简单与批量 Span 处理器api/exporters.rstHTTPSpanExporter、GRPCSpanExporterHTTP 与 gRPC Span 导出器api/settings.rstphoenix.otel.settings配置与环境变量解析理解这些页面描述的对象是理解文档站为何如此组织的前提后文将结合 otel.py 与 settings.py 的源码进一步展开。二、在本地构建文档原文档 docs/README.md 给出了三条构建步骤这是任何文档维护工作的起点。1. 安装依赖pip install -r requirements.txt pip install -e .. # Install phoenix-otel package in development mode第一条命令安装 Sphinx 文档构建所需的依赖。查看 docs/requirements.txt 可知构建环境包含以下组件myst_parser让 Sphinx 支持 MarkdownMyST语法文档主页index.md正是靠它渲染sphinx7.3.7文档构建器本体版本被固定以保证构建可复现pydata-sphinx-theme文档 HTML 主题linkify-it-pyMyST 的链接自动补全autolink支持sphinx_design提供卡片、网格等页面设计组件-e packages/phoenix-otel以可编辑模式development mode把包自身链接进环境——注意这里是相对当前仓库根目录的写法在仓库根目录执行即可让pip install -e packages/phoenix-otel同时生效。第二条pip install -e ..表示从docs/的上级目录即包根目录以可编辑模式安装arize-phoenix-otel。这样做的关键原因在 source/conf.py 中可以看到Sphinx 的 autodoc 扩展需要在构建时import被文档化的包conf.py 将BASE_DIR设为文档目录的上三级即包根目录并把src/phoenix插入sys.path随后 autodoc 才能从源码中抽取 docstring 生成 API 文档。2. 构建 HTMLmake html该命令由 docs/Makefile 定义SPHINXOPTS可选附加构建参数SOURCEDIR source指向文档源BUILDDIR build是输出目录。make html实际执行sphinx-build -M html source build。在 Windows 环境下仓库同时提供了 make.bat可执行make.bat html达到同样效果。执行后生成的 HTML 输出在build/html/目录下。3. 本地查看open build/html/index.html在 Linux 桌面环境可改用xdg-open build/html/index.html文档主体从build/html/index.html进入。构建过程中autodoc 会读取phoenix.otel各模块的 docstring 并渲染出Register、TracerProvider、Processors、Exporters、Settings五个 API 页面与index.md中的 toctree 一一对应。三、文档目录结构逐层解析原文档列出的结构如下结合仓库实际内容可逐项展开docs/ ├── source/ │ ├── conf.py # Sphinx 配置 │ ├── index.md # 主文档页 │ ├── api/ # API 参考文件5 个 .rst │ ├── _static/ # 静态资源CSS、图片等 │ └── _templates/ # Sphinx 模板 ├── requirements.txt # 构建文档的 Python 依赖 ├── Makefile # Unix 构建入口 └── make.bat # Windows 构建入口conf.py构建行为的心脏source/conf.py 中值得注意的配置点包括项目元信息与版本L14-L27project Phoenix OTEL Reference版本号直接从包内读取from phoenix.otel import __version__若导入失败则回退为latest保证每次构建的版本号与实际包版本一致。源码后缀L31source_suffix [.rst, .md, .txt]因此index.md能作为 Sphinx 源文件参与构建。扩展列表L33-L39autodoc从 docstring 生成 API 文档、autosummary生成 API 摘要表、napoleon解析 Google/Numpy 风格 docstring、myst_parserMarkdown 支持、sphinx_design页面组件。autodoc 行为L63-L77autoclass_content class类文档含__init__docstring、autodoc_typehints none不渲染类型注解、autodoc_preserve_defaults True保留参数默认值原文、add_module_names False不显示模块前缀并默认对类成员members: True、show-inheritance: False。这些配置直接决定了五个api/*.rst页面中函数与类的呈现方式。MyST 扩展L60-L61启用colon_fence冒号围栏代码块、linkify链接自动化、substitution文本替换myst_heading_anchors 2让标题自动生成锚点。主题与版本切换L93-L131HTML 使用pydata_sphinx_theme加载 custom.css 与 custom_sidebar.htmljson_url指向 Read the Docs 的 switcher.json配合READTHEDOCS_VERSION环境变量实现多版本切换下拉框L85-L89。其余组成部分index.md文档主页同时承担快速开始职责内含register()用法、端点配置、环境变量、装饰器chain/agent/tool/llm/retriever/embedding等大量可运行示例并以toctree收纳五个 API 参考页见 index.md。api/*.rst五个 RST 文件分别通过autofunction、autoclass、automodule指令把源码中的符号实时渲染为文档如 api/register.rst 中.. autofunction:: phoenix.otel.register。因此维护文档的主要内容是维护源码 docstringRST 文件只是索引。_static/custom.css主题定制样式、logo.png站点 Logo、switcher.json版本切换数据。_templates/custom_sidebar.html替换默认侧边栏渲染。四、Read the Docs 自动部署原文档说明文档在以下时机被自动构建并部署到 Read the DocsRTD代码推送到main分支时创建新 tag 时。这样每次合并文档改动或发布新版本文档站都会自动重建无需手动触发部署。原文档还指出 RTD 配置文件位于包根目录的.readthedocs.yaml需要注意的是该文件属于被忽略的发布配置当前仓库文件列表中没有出现该文件实际部署时的项目配置以发布流程使用的为准本地构建与验证流程不受其影响。conf.py中已经内置了 RTD 相关的适配逻辑通过读取READTHEDOCS_VERSION环境变量conf.py L86-L89来匹配switcher.json中的版本条目从而实现文档站的latest/stable/特定版本切换。这意味着只要在 RTD 上开启构建版本下拉框即可自动工作。五、维护与更新 API 文档原文档给出了更新 API 文档的五个步骤结合仓库实际组织方式可细化如下新增模块时生成 RST运行sphinx-apidoc为新的包/模块生成.rst文件例如sphinx-apidoc -o source/api ../src/phoenix/otel。更新 API 参考索引当前仓库将 API 参考拆分为五个主题文件而非单一的otel.rst因此新符号应按主题放入对应的 register.rst、provider.rst、processors.rst、exporters.rst 或 settings.rst若符号所属主题在文档中尚无对应页面则需新建 RST 文件并在 index.md 的 toctree 中登记。必要时更新 index.md主页上的快速开始示例、环境变量表、装饰器示例等若有变化需同步维护例如register()新参数、新增环境变量。本地验证执行make html重点检查新增 API 页是否被正确渲染、toctree 是否报出文档未包含在任意 toctree警告。提交并推送推送到main分支后由 RTD 自动部署。由于 autodoc 直接从 docstring 取内容以下源码注释规范会直接影响文档质量conf.py中启用了napoleon_google_docstring True与napoleon_numpy_docstring Trueconf.py L52-L54因此为新增函数/类编写 Google 或 NumPy 风格的 docstring含Args:、Returns:、Raises:、Examples:小节即可被自动渲染为标准 API 文档。六、被文档化的核心 API结合源码深入理解文档站描述的 API 不仅是使用说明其行为可以从 otel.py 与 settings.py 的源码得到验证。register()一站式入口register()定义于 otel.py L65-L197是文档主页推荐的入门方式。其完整参数如下均带默认值全部为关键字参数参数默认值作用endpointNone收集器端点未指定时读取PHOENIX_COLLECTOR_ENDPOINT并默认落到http://localhost:6006HTTP 路径或 gRPC 默认端口project_nameNone项目名未指定时读取PHOENIX_PROJECT_NAMEbatchFalseTrue时使用BatchSpanProcessor批量导出False时逐条使用SimpleSpanProcessorset_global_tracer_providerTrue是否将生成的 TracerProvider 设为 OpenTelemetry 全局默认headersNone发往收集器的请求头未指定时读取PHOENIX_CLIENT_HEADERSprotocolNone传输协议仅允许http/protobuf或grpc不指定时按端点自动推断verboseTrue是否向 stdout 打印配置明细auto_instrumentFalse是否自动插桩所有已安装的 OpenInference 库api_keyNoneAPI 密钥未指定时读取PHOENIX_API_KEY源码中几个值得注意的实现细节project_name 的强制注入otel.py L146-L159若未显式传resourceregister()会用Resource.create({PROJECT_NAME: project_name})创建资源若已传resource则通过existing_resource.merge(project_resource)把项目名合并进去避免覆盖用户自定义属性。api_key 的 header 注入otel.py L164-L170传入api_key时会自动生成authorization: Bearer key请求头对原headers字典做拷贝不污染调用方对象。自动插桩机制otel.py L819-L831auto_instrumentTrue通过importlib.metadata.entry_points(groupopeninference_instrumentor)发现并加载所有已安装的 OpenInference 插桩库如openinference-instrumentation-openai、-langchain、-llama-index等逐一调用其instrument()。若未安装任何插桩库会输出警告并跳过这解释了文档主页中的提示需先安装对应的 OpenInference instrumentation 包。TracerProviderPhoenix 感知的端点推断TracerProvider 继承自 OpenInference 的 TracerProvider核心增强点端点自动推断otel.py L263-L276协议由OTLPTransportProtocol枚举http/protobuf、grpc、infer归一化_maybe_http_endpoint依据 URL 路径是否为/v1/traces判断 HTTP 端点_maybe_grpc_endpoint依据路径为空且端口等于PHOENIX_GRPC_PORT默认 4317判断 gRPC 端点otel.py L707-L716。这就是文档所述HTTP 需完整路径http://localhost:6006/v1/traces而 gRPC 默认端口是 4317的代码依据。默认处理器语义otel.py L280-L311TracerProvider 会自动创建一个默认 SpanProcessor此时调用add_span_processor()默认会替换该默认处理器先_shutdown_default_processor()再挂新处理器传入replace_default_processorFalse则保留默认处理器、追加新处理器——对应文档中的Multiple Span Processors示例。verbose 明细输出otel.py L313-L379打印项目名、Span Processor 类型、收集器端点、传输协议HTTPprotobuf 或 gRPC、请求头值被_printable_headers统一打码为****避免泄露密钥并在使用SimpleSpanProcessor时提示生产环境建议改用BatchSpanProcessor。Span Processors 与 ExportersSimpleSpanProcessor 与 BatchSpanProcessor 均支持直接传入endpoint/headers/protocol而省略span_exporter由内部自动选择HTTPSpanExporter或GRPCSpanExporter若端点无法推断协议会warnings.warn并回退到 HTTP。Batch 处理器还透传max_queue_size、schedule_delay_millis、max_export_batch_size、export_timeout_millis等批处理参数对应OTEL_BSP_*系列环境变量。HTTPSpanExporter 与 GRPCSpanExporter 在未显式传headers时会合并PHOENIX_CLIENT_HEADERS解析出的请求头与PHOENIX_API_KEY生成的authorization头若显式传了headers则统一转为小写键并在缺失authorization时自动补上 API Key 头。环境变量与配置解析文档主页列出的 Phoenix 专属环境变量及其在 settings.py 中的实现环境变量作用源码依据PHOENIX_COLLECTOR_ENDPOINT收集器端点如https://your-phoenix.com:6006优先级高于OTEL_EXPORTER_OTLP_ENDPOINTget_env_collector_endpointPHOENIX_PROJECT_NAMESpan 关联的项目名默认defaultPHOENIX_PROJECT是其规范名两者同时设置时规范名优先并发出一次性警告get_env_project_namePHOENIX_API_KEY用户/系统 API Key自动生成authorization: Bearer key头get_env_phoenix_auth_headerPHOENIX_GRPC_PORTgRPC 端口覆盖默认 4317OTLP/gRPC 标准端口非法值在进程环境中直接抛ValueErrorget_env_grpc_portPHOENIX_CLIENT_HEADERS附加请求头按 W3C Baggage HTTP Header 格式编码如AuthorizationBearer token,custom-headervalue支持 URL 编码并会尝试纠正未编码的值get_env_client_headers、parse_env_headers此外settings.py还支持从当前工作目录向上查找.env.phoenix凭据交接文件settings.py L81-L96进程环境变量始终优先文件仅接受PHOENIX_前缀的合法键且必须是当前用户拥有的常规文件超过 64KB 会被忽略并告警文件权限对其他用户开放时如chmod 600建议会记录日志警告可通过PHOENIX_DISCOVER_CONFIGfalse关闭文件发现长驻进程修改文件后调用clear_env_file_cache()可重新发现。这些细节并未全部写入文档主页但属于api/settings.rst所文档化的phoenix.otel.settings模块行为是排查为何环境变量不生效问题时的关键线索。七、维护与排障要点综合原文档与源码在构建文档站和使用其描述的 API 时有几个容易踩坑的地方值得特别注意本地构建前必须先安装包pip install -e packages/phoenix-otel缺一不可否则conf.py中from phoenix.otel import __version__会失败autodoc 页面也将缺少内容。HTTP 端点必须带完整路径register(endpointhttp://localhost:6006/v1/traces)是完整形式仅写http://localhost:6006会被按 gRPC 端口语义处理。也可用protocol参数强制指定http/protobuf或grpc来绕过推断。生产环境优先batchTrueSimpleSpanProcessor是逐条同步导出BatchSpanProcessor在后台批量导出、不阻塞应用这也是TracerProviderverbose 输出会主动提示的原因。文档内容主要靠 docstring 驱动RST 文件只做符号索引维护文档的实质是维护phoenix.otel各模块的 Google/NumPy 风格 docstring改完务必make html验证再推送main分支触发 RTD 重建。敏感信息打码register(verboseTrue)打印的请求头值均为****排查认证问题时不要指望从 stdout 看到完整 token应以PHOENIX_API_KEY/PHOENIX_CLIENT_HEADERS的实际配置为准。文档站的测试保障可以从 tests/ 目录中看到端倪test_exports.py、test_otel.py、test_settings.py三个测试文件分别覆盖导出器、register/TracerProvider组合行为与 settings 环境变量解析说明文档所描述的行为端点推断、请求头合并、环境变量优先级等均有自动化测试背书可作为维护文档时的行为参照。本文核心要点arize-phoenix-otel的文档站是一套由 Sphinx autodoc MyST pydata-sphinx-theme 驱动的标准 API 文档项目构建链路为pip install -r requirements.txt pip install -e packages/phoenix-otel make html其五个 API 参考页全部由源码 docstring 实时生成维护文档即维护 docstring推送到main或打 tag 后由 Read the Docs 自动部署并支持版本切换。掌握这套流程后你既可以独立复现本地构建也能为新增的追踪能力、导出器或环境变量顺畅地补充官方文档。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐Phoenix API 参考文档构建与托管指南基于 Sphinx Read the Docs 的维护实战Phoenix API 参考文档构建与托管指南基于 Sphinx Read the Docs 的维护实战 导读 本指南完整讲解 Arize Phoenix可观测性AI 评测LLMOpsAI 应用人工智能Read the Docs 文档构建实践指南:Sphinx sphinx-multiproject 双文档集与本地热重载工作流Read the Docs 文档构建实践指南:Sphinx sphinx multiproject 双文档集与本地热重载工作流 Read the Docs后端文档gpt-engineer 文档构建指南基于 Sphinx Read the Docs 的本地与云端构建全流程gpt engineer 文档构建指南基于 Sphinx Read the Docs 的本地与云端构建全流程 gpt engineer 的官方文档位于仓库人工智能AI 应用代码智能体AI AgentAI 评测上一篇slotmap核心容器全解析SlotMap、HopSlotMap与DenseSlotMap对比下一篇Whisper.cpp模型选择完全指南从入门到精通的实用决策方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考