# LlamaIndex框架 观测功能支持通过Python探针对LlamaIndex智能体进行观测，Python探针是华为云AgentArts产品自研的Python语言的可观测采集探针，其基于OpenTelemetry标准实现了自动化埋点能力。 本章节针对使用LlamaIndex框架开发的第三方智能体应用，通过Python探针实现自动化埋点和数据上报。 #### 前提条件 - Python 环境版本 \>= 3.9 - LlamaIndex版本 \>= 0.10.0。 探针初始化需要在应用启动时完成，建议在导入LlamaIndex模块之前初始化。 ![](https://support.huaweicloud.com/ops-agentarts/public_sys-resources/note_3.0-zh-cn.png) - 在AgentArts观测界面查看数据不收费。 - 但数据上报会产生费用： - 调用链上报到APM（应用性能管理服务），费用明细请参考[APM计费说明](https://support.huaweicloud.com/price-apm2/apm_07_0019.html)。 - 指标上报到AOM（应用运维管理服务），费用明细请参考[AOM计费说明](https://support.huaweicloud.com/price-aom2/aom_07_0004.html)。 - AOM和APM都是按需计费，并有一定量的免费额度，超出后按实际使用量收费。 #### 框架介绍 LlamaIndex是一个面向大语言模型应用开发的数据框架，提供了Agent编排、工作流（Workflow）、检索增强生成（RAG）、工具集成等能力，帮助开发者快速搭建复杂的LLM应用。 接入后，以下能力将被自动监控： - Agent执行链路（invoke_agent）：Agent回合的完整生命周期。 - 推理步骤（react step）：每轮"模型推理 + 工具调用"的详细过程。 - LLM调用（chat）：模型名称、Token用量、输入/输出内容、流式响应的首Token时延（TTFT）和Token间时延（TBT）。 - 工具调用（execute_tool）：工具名称、输入参数、返回结果。 - 工作流执行链路（workflow/execute_task）：工作流各环节的执行过程。 - RAG检索链路：检索（retrieve，含召回属性）、嵌入（embed step，含模型名/向量维度）、合成（synthesize）。 #### 下载探针 接入AgentArts观测功能需要以下文件，请提前下载到目标机器的同一个目录下： 表1探针文件清单 | 文件 | 说明 | |:---|:---| | [\*_opentelemetry_instrumentation_llama_index-\*.whl](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.10.30/huaweicloud_opentelemetry_instrumentation_llama_index-1.0.1-py3-none-any.whl) | 探针文件（Python wheel安装包，用于pip安装） | | [install.py](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.10.30/install.py) | 一键部署脚本（跨平台，Windows/Linux通用） | | [install_env.ps1](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.10.30/install_env.ps1) | 环境变量部署脚本（Windows用） | | [install_env.sh](https://obs-apm2-cn-southwest-2.obs.cn-southwest-2.myhuaweicloud.com/PYTHON/version.26.10.30/install_env.sh) | 环境变量部署脚本（Linux用） | 上表中的文件名含通配符\*，实际下载的文件会包含具体版本号，部署时请使用实际文件名。 下载完成后，建议将文件统一放在一个目录中（如llama_probe_verify/），后续操作均在该目录下执行。 #### 接入步骤 #### 步骤一：获取接入参数 1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。 2. 在左侧导航栏选择"观测与优化 \> 观测"。 3. 在"智能体列表"页面，单击"接入智能体"，按照页面指引填写名称、智能体类型，创建一个"LlamaIndex"框架的智能体，并获取各配置参数。 图1获取配置参数 ![](https://support.huaweicloud.com/ops-agentarts/zh-cn_image_0000002803553797.png "点击放大") #### 步骤二：安装探针方式一，一键部署 LlamaIndex探针提供两种安装部署方式，本节介绍使用方式一进行安装： - **方式一（推荐）：一键部署**，通过install.py脚本传入命令行参数，自动完成探针安装和配置写入。适用于常规部署场景。 - 方式二：环境变量部署，先在当前会话中设置环境变量，再执行install_env.ps1（Windows）或install_env.sh（Linux）完成安装。适用于配置由外部系统注入环境变量的场景。 两种方式的最终效果完全一致：安装探针whl包 + 生成\~/.llama-index-metrics/config.json配置文件。 进入[下载探针]中下载探针文件的目录，install.py是跨平台Python脚本，Windows / Linux均用同一脚本，参数与行为完全一致。执行install.py后，脚本会自动完成以下操作： 1. 校验whl文件是否存在。 2. 第1次执行pip install --force-reinstall --no-deps：只强制重装探针whl本身，不碰依赖。 3. 第2次执行pip install（不带force）：补装缺失依赖，已存在的组件自动跳过（不强制重装、不覆盖已有版本）。 4. 检查是否已安装llama-index，未安装时自动执行pip install llama-index，已安装则跳过。 5. 生成\~/.llama-index-metrics/config.json配置文件（携带参数注入，JSONC注释模板）。 - Windows路径：C:\\Users\\\<用户名\>\\.llama-index-metrics\\config.json - Linux路径：/home/\<用户名\>/.llama-index-metrics/config.json 6. 提示三种启动方式（见[步骤三：启动应用]）。 7. Linux下额外添加+x权限（首次执行后即可./install.py直接运行）。 **Windows环境（PowerShell）** 1. 进入探针文件所在目录。 ``` cd <探针文件所在目录> ``` 2. 执行安装命令，将参数替换为[步骤一：获取接入参数]中获取的实际值。 PowerShell（用反引号\`续行，或写成一行）： ``` python install.py --whl *_opentelemetry_instrumentation_llama_index-*.whl --agent-id --domain-id --project-id --endpoint --token --aom-endpoint --aom-access-code --aom-prometheus-id --resource-type agent ``` **\*_opentelemetry_instrumentation_llama_index-\*.whl为通配符，实际使用时替换为真实的whl文件名。** 表2install.py参数说明 | 参数 | 是否必填 | 说明 | |:---|:---|:---| | --whl | 是 | 探针wheel文件路径，请按[下载探针]实际获取的探针填写。 | | --agent-id | 是 | 智能体ID。 | | --domain-id | 是 | 账号domain ID。 | | --project-id | 是 | 华为云项目ID。 | | --endpoint | 是 | APM数据上报地址。 | | --token | 是 | APM接入凭证Token。 | | --aom-endpoint | 是 | AOM数据上报地址。 | | --aom-access-code | 是 | AOM接入凭证Access Code。 | | --aom-prometheus-id | 是 | AOM Prometheus实例ID | | --resource-type | 是 | 智能体类型：agent（单智能体）、multiagents（多智能体）、workflow（工作流）。 | 3. 执行完毕后，确认安装结果： - 探针whl已安装到Python的site-packages，执行pip show huaweicloud-opentelemetry-instrumentation-llama-index可验证。 - 配置文件生成在C:\\Users\\\<用户名\>\\.llama-index-metrics\\config.json。 - 日志目录在C:\\Users\\\<用户名\>\\.llama-index-metrics\\data\\logs\\plugin-YYYY-MM-DD.log。 **Linux环境（bash / sh）** 1. 进入探针文件所在目录。 ``` cd <探针文件所在目录> ``` 2. 执行安装命令，将参数替换为[步骤一：获取接入参数]中获取的实际值。 ``` python3 install.py \ --whl *_opentelemetry_instrumentation_llama_index-*.whl \ --agent-id \ --domain-id \ --project-id \ --endpoint \ --token \ --aom-endpoint \ --aom-access-code \ --aom-prometheus-id \ --resource-type agent ``` **\*_opentelemetry_instrumentation_llama_index-\*.whl为通配符，实际使用时替换为真实的whl文件名。** 首次执行后install.py自动获得+x权限，后续可直接./install.py运行。 表3install.py参数说明 | 参数 | 是否必填 | 说明 | |:---|:---|:---| | --whl | 是 | 探针wheel文件路径，请按[下载探针](https://support.huaweicloud.com/ops-agentarts/agentarts_14_0171.html#agentarts_14_0171__section1215794931513)实际获取的探针填写。 | | --agent-id | 是 | 智能体ID。 | | --domain-id | 是 | 账号domain ID。 | | --project-id | 是 | 华为云项目ID。 | | --endpoint | 是 | APM数据上报地址。 | | --token | 是 | APM接入凭证Token。 | | --aom-endpoint | 是 | AOM数据上报地址。 | | --aom-access-code | 是 | AOM接入凭证Access Code。 | | --aom-prometheus-id | 是 | AOM Prometheus实例ID | | --resource-type | 是 | 智能体类型：agent（单智能体）、multiagents（多智能体）、workflow（工作流）。 | 3. 执行完毕后，确认安装结果： - 探针whl已安装到Python的site-packages，执行python3 -m pip show huaweicloud-opentelemetry-instrumentation-llama-index可验证。 - 配置文件生成在/home/\<用户名\>/.llama-index-metrics/config.json。 - 日志目录在/home/\<用户名\>/.llama-index-metrics/data/logs/plugin-YYYY-MM-DD.log。 #### 步骤二：安装探针方式二，环境变量部署 LlamaIndex探针提供两种安装部署方式，本节介绍使用方式二进行安装： - 方式一（推荐）：一键部署，通过install.py脚本传入命令行参数，自动完成探针安装和配置写入。适用于常规部署场景。 - **方式二：环境变量部署**，先在当前会话中设置环境变量，再执行install_env.ps1（Windows）或install_env.sh（Linux）完成安装。适用于配置由外部系统注入环境变量的场景。 两种方式的最终效果完全一致：安装探针whl包 + 生成\~/.llama-index-metrics/config.json配置文件。 环境变量部署适用于配置由外部系统注入环境变量的场景。先在当前会话中设置环境变量，再执行部署脚本将环境变量写入config.json。部署脚本（install_env.ps1 / install_env.sh）会自动完成以下操作： 1. 校验whl文件是否存在。 2. 第1次执行pip install --force-reinstall --no-deps：只强制重装探针whl本身。 3. 第2次执行pip install（不带force）：补装缺失依赖，已存在的组件自动跳过。 4. 检查是否已安装llama-index，未安装时自动安装。 5. 验证whl已安装（pip show版本对比）。 6. 读取当前会话的环境变量，写入\~/.llama-index-metrics/config.json。 7. 打印缺失的环境变量（WARN提示，不阻断执行）。 8. 提示三种启动方式（见[步骤三：启动应用]）。 **Windows部署（PowerShell）** 1. 刷新环境变量（每次打开新窗口都要执行）。将值替换为[步骤一：获取接入参数]中获取的实际值。 ``` $env:agentarts_agentops_otel_agent_apm_enable="true" $env:agentarts_agentops_otel_agent_aom_enable="true" $env:agent_domain_id="" $env:agentarts_project_id="" $env:agent_resource_id="" $env:resource_type="agent" $env:agentarts_agentops_apm_token="" $env:agentarts_agentops_apm_exporter_endpoint="" $env:agentarts_agentops_aom_access_code="" $env:agentarts_agentops_aom_exporter_endpoint="" $env:agentarts_agentops_aom_prometheus_id="" ``` 2. 进入探针文件所在目录，执行部署脚本。 ``` cd <探针文件所在目录> powershell -ExecutionPolicy Bypass -File install_env.ps1 -Whl *_opentelemetry_instrumentation_llama_index-*.whl ``` \*_opentelemetry_instrumentation_llama_index-\*.whl为通配符，实际使用时替换为真实的whl文件名。 3. 执行后验证。 ``` # 查看config.json内容 type C:\Users\<用户名>\.llama-index-metrics\config.json # 确认探针已安装 python -m pip show huaweicloud-opentelemetry-instrumentation-llama-index ``` **Linux部署（bash / sh）** 1. 刷新环境变量（每次打开新终端都要执行）。将值替换为[步骤一：获取接入参数]中获取的实际值。 ``` export agentarts_agentops_otel_agent_apm_enable=true export agentarts_agentops_otel_agent_aom_enable=true export agent_domain_id= export agentarts_project_id= export agent_resource_id= export resource_type=agent export agentarts_agentops_apm_token= export agentarts_agentops_apm_exporter_endpoint= export agentarts_agentops_aom_access_code= export agentarts_agentops_aom_exporter_endpoint= export agentarts_agentops_aom_prometheus_id= ``` 2. 进入探针文件所在目录，执行部署脚本。 ``` cd <探针文件所在目录> sh install_env.sh *_opentelemetry_instrumentation_llama_index-*.whl ``` \*_opentelemetry_instrumentation_llama_index-\*.whl为通配符，实际使用时替换为真实的whl文件名。 3. 执行后验证。 ``` # 查看config.json内容 cat $HOME/.llama-index-metrics/config.json # 确认探针已安装 python3 -m pip show huaweicloud-opentelemetry-instrumentation-llama-index ``` #### 步骤三：启动应用 无论通过方式一（一键部署）还是方式二（环境变量部署）完成安装，启动方式完全相同。 探针安装完成后，提供三种启动方式，可任选其一。 以下命令中的app.py为您的LlamaIndex应用入口文件，可参考本文档[示例代码]章节编写一个完整的Agent应用。 **方式1：opentelemetry-instrument（推荐，零代码侵入）** ``` opentelemetry-instrument python app.py ``` 启动器自动装配：读entry point → 设置环境变量 → 读取config.json建立Provider → 注册回调/patch Workflow.run → 然后执行业务代码。无需修改任何业务代码。 **方式2：sitecustomize.py（交互式场景使用）** opentelemetry-instrument在Windows Git Bash下stdin有兼容问题，交互式（input）场景建议用sitecustomize方式： 1. 创建sitecustomize.py文件（放在任意PYTHONPATH目录下）： ``` cat > sitecustomize.py <<'EOF' from opentelemetry.instrumentation.huawei_llama_index import auto_instrument auto_instrument() EOF ``` 2. 指定PYTHONPATH后用python直接启动（不用opentelemetry-instrument）： ``` # Windows（PATH分隔符;） set PYTHONPATH=%CD%;%CD%\examples && python app.py # Linux / Git Bash（PATH分隔符:） PYTHONPATH="$PWD:$PWD/examples" python app.py ``` **方式3：业务代码手动调用** 在业务代码中手动调用初始化函数，在应用入口文件的开头添加： ``` from opentelemetry.instrumentation.huawei_llama_index import auto_instrument auto_instrument() ``` #### 步骤四：验证数据上报 应用启动并产生调用后，可通过日志和AgentArts平台确认数据上报是否成功。 **日志确认** 探针运行日志位于以下路径： - Windows：C:\\Users\\\<用户名\>\\.llama-index-metrics\\data\\logs\\plugin-YYYY-MM-DD.log - Linux：/home/\<用户名\>/.llama-index-metrics/data/logs/plugin-YYYY-MM-DD.log ``` # 查看日志文件是否存在 ls ~/.llama-index-metrics/data/logs/plugin-*.log # 确认APM/AOM上报是否成功 grep -E "export SUCCESS|export FAILED" ~/.llama-index-metrics/data/logs/plugin-*.log ``` 日志中出现APM (Traces) export SUCCESS和AOM (Metrics) export SUCCESS表示数据上报成功。 **AgentArts平台确认** 登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/)，在"观测与优化 \> 观测"页面中找到已接入的智能体，查看各指标与会话数据。 #### 配置参数说明 探针安装后，配置集中在\~/.llama-index-metrics/config.json中（Windows路径：C:\\Users\\\<用户名\>\\.llama-index-metrics\\config.json，Linux路径：$HOME/.llama-index-metrics/config.json）。一键部署由install.py自动生成，环境变量部署由install_env.\*脚本写入。 探针启动时按以下优先级读取配置：**config.json otel段 \> 环境变量（同名key）\> 默认值**。 - 环境变量key与config.json otel段key**完全同名**。 - 部署脚本做的事：把当前会话的环境变量（11个key）读出来 → 写入config.json的otel段。 - 探针启动时读到同一位置的config.json，配置生效。 表4环境变量与config.json字段对照表 | 环境变量 / config.json字段 | 是否必填 | 默认值 | 说明 | |:---|:---|:---|:---| | agentarts_agentops_otel_agent_apm_enable | 是 | true | 是否启用APM调用链上报。 | | agentarts_agentops_otel_agent_aom_enable | 是 | true | 是否启用AOM指标上报。 | | agent_domain_id | 是 | - | 账号domain ID。 | | agentarts_project_id | 是 | - | 华为云项目ID。 | | agent_resource_id | 是 | - | 智能体ID。 | | resource_type | 是 | - | 智能体类型：agent（单智能体）、multiagents（多智能体）、workflow（工作流）。 | | agentarts_agentops_apm_token | 启用APM时必填 | - | APM接入凭证Token。 | | agentarts_agentops_apm_exporter_endpoint | 启用APM时必填 | - | APM数据上报地址。 | | agentarts_agentops_aom_access_code | 启用AOM时必填 | - | AOM接入凭证Access Code。 | | agentarts_agentops_aom_exporter_endpoint | 启用AOM时必填 | - | AOM数据上报地址。 | | agentarts_agentops_aom_prometheus_id | 启用AOM时必填 | - | AOM Prometheus实例ID。 | #### 示例代码 以下示例展示了一个基于LlamaIndex的ReAct Agent应用，包含工具调用和多轮问答： 前提条件 - LlamaIndex框架（pip install llama-index，探针部署脚本会自动安装）。 - 已安装LlamaIndex探针并完成配置，详细操作详见[接入步骤]。 - 示例中使用华为云MaaS服务提供的大模型接口，可登录华为云[MaaS服务控制台](https://console.huaweicloud.com/modelarts/#/model-studio/homepage)，创建API Key。 示例代码 将以下代码保存为app.py。 ``` from llama_index.core.agent import ReActAgent from llama_index.core.tools import FunctionTool from llama_index.llms.openai import OpenAI # 定义工具函数 def search_product(keyword: str) -> str: """根据关键词搜索华为云产品信息""" products = { "ECS": "弹性云服务器，提供安全可靠、弹性伸缩的云服务器，支持多种规格按需选购", "RDS": "关系型数据库服务，支持 MySQL/PostgreSQL/SQL Server，提供高可用和自动备份", "OBS": "对象存储服务，海量、安全、高可靠的云存储，适用于数据湖、备份归档等场景", } return products.get(keyword.upper(), f"未找到 '{keyword}' 相关产品") def get_product_usecase(service_name: str) -> str: """查询华为云产品的典型使用场景""" usecases = { "ECS": "适用场景：Web应用托管、开发测试环境搭建、企业应用迁移上云、高性能计算任务", "RDS": "适用场景：电商交易系统、金融业务数据库、企业ERP/CRM系统、移动应用后端存储", "OBS": "适用场景：静态网站托管、大数据分析存储、备份与归档、音视频内容分发", } return usecases.get(service_name.upper(), f"暂无 '{service_name}' 的场景信息") # 创建工具 search_tool = FunctionTool.from_defaults(fn=search_product) usecase_tool = FunctionTool.from_defaults(fn=get_product_usecase) # 创建LLM实例（使用华为云MaaS OpenAI兼容接口） llm = OpenAI( model="deepseek-v4.1-flash", base_url="https://api.modelarts-maas.com/openai/v1", api_key="", # 替换为在华为云MaaS控制台申请的API Key ) # 创建Agent agent = ReActAgent.from_tools([search_tool, usecase_tool], llm=llm) # 运行Agent response = agent.chat("帮我介绍一下ECS和OBS，以及它们分别适合用在哪些场景？") print(response) ``` 在配置好环境变量的终端中执行以下命令，通过探针启动应用： ``` opentelemetry-instrument python app.py ``` 探针会自动采集Agent执行链路中的所有LLM调用、工具调用等数据，无需修改任何业务代码。 #### 查看监控数据 数据上报成功后，可在 AgentArts 智能体平台的观测功能中查看监控数据。 1. 登录[AgentArts 智能体平台](https://console.huaweicloud.com/agentarts/)。 2. 在左侧导航栏选择"观测与优化 \> 观测"。 3. 在"智能体列表"页面，找到已接入的智能体，单击智能体名称进入详情页面。 **查看业务指标** 在"指标分析"页签中，可以查看关键业务指标： - Tokens消耗：Input Tokens和Output Tokens的消耗总量 - 模型调用次数：应用调用大模型的累计次数 - 模型调用平均耗时：模型调用的平均响应时间 - 模型调用成功率：大模型调用成功的比例 - 会话数：应用产生的会话总数 - 响应成功率：服务响应的成功率 **查看调用链信息** 在"调用链分析"页签中，可以查看完整的Trace调用链路： - 查看各Span类型的层级关系及各节点耗时 - 单击具体Span查看详细信息： - LLM节点：可查看模型名称、输入/输出消息（Input/Output Messages）、Token消耗（Total tokens） - Tool节点：可查看工具名称、输入参数、返回结果 - LangGraph节点：可查看图节点执行顺序、状态转换 **查看会话分析** 在"会话分析"页签中，可以查看智能体与用户对话的历史数据： - 追踪对话上下文 - 分析模型响应耗时 - 统计Token消耗 - 快速定位对话异常问题 #### 更多参考 **传递session_id与user_id** 在调用agent.invoke时，可通过OTel Baggage传递会话信息，传入session_id和user_id，探针自动关联到span用于会话分析和用户分析： ``` from opentelemetry.baggage import set_baggage from opentelemetry import context as ctx_api context = set_baggage("session_id", "session-01") context = set_baggage("user_id", "llama_user", context) token = ctx_api.attach(context) try: response = agent.chat("您好") finally: ctx_api.detach(token) ``` - session_id：会话标识，用于关联同一会话内的多轮调用。 - user_id：用户标识，用于按用户维度统计和过滤。 **控制内容采集** 默认情况下，探针会采集LLM的输入/输出内容。如需关闭： ``` export captureMessageContent=false ``` **代码手动插桩** 如果无法使用opentelemetry-instrument命令自动插桩，也可以通过创建sitecustomize.py手动初始化： ``` import os os.environ["OTEL_PYTHON_LOG_CORRELATION"] = "True" os.environ["OTEL_PYTHON_LOG_LEVEL"] = "debug" # 设置日志级别，可根据情况调整 os.environ["OTEL_PYTHON_LOG_FORMAT"] = "%(asctime)s [%(levelname)s] [trace_id=%(otelTraceID)s span_id=%(otelSpanID)s] %(message)s" import logging from opentelemetry.instrumentation.logging import LoggingInstrumentor root_logger = logging.getLogger() root_logger.handlers.clear() root_logger.setLevel(logging.DEBUG) # 设置日志级别，可根据情况调整 LoggingInstrumentor().instrument( set_logging_format=True, log_level=logging.DEBUG # 设置日志级别，可根据情况调整，确保 OTel 的 Handler 也接受对应日志级别 ) from opentelemetry.instrumentation.huawei_llama_index import auto_instrument auto_instrument() ``` #### 常见问题 **探针未装配（无OTEL_PROBE日志）** 应用启动后，探针运行日志目录（\~/.llama-index-metrics/data/logs/）下没有生成plugin-\*.log文件，日志中搜索不到OTEL_PROBE关键字，AgentArts观测页面也无任何数据。 产生该问题的原因是探针未被正确装配导致，常见原因包括：部署脚本未执行或执行失败、whl文件未成功安装到site-packages、whl的entry point未注册（导致opentelemetry-instrument启动器无法发现探针）、config.json中APM/AOM开关为false（默认值）。 1. 执行pip show huaweicloud-opentelemetry-instrumentation-llama-index，确认探针已安装。如果未安装，说明部署脚本未执行或执行失败，请重新执行步骤二中的部署命令。 2. 检查pip show输出中是否包含entry point信息。如果entry point缺失，opentelemetry-instrument启动器将无法自动装配探针，请重新执行部署脚本重装whl。 3. 确认config.json（位于\~/.llama-index-metrics/config.json）中agentarts_agentops_otel_agent_apm_enable和agentarts_agentops_otel_agent_aom_enable是否为true，默认值为true，表示不上报任何数据。如果为false，请修改为true或重新执行部署脚本并确保参数正确传入。 **已经设置环境变量，但config.json为空** 使用环境变量部署方式时，已设置环境变量但执行部署脚本后config.json内容为空或缺少otel段。产生原因是部署脚本（install_env.ps1 / install_env.sh）从当前会话的环境变量中读取配置并写入config.json。如果在执行脚本前未在同一会话中刷新环境变量，脚本读取不到配置，config.json将为空。环境变量仅在当前终端会话有效，每次打开新终端或新窗口都需要重新设置。 解决方案：确保在执行部署脚本的**同一终端/窗口** 中先刷新环境变量，再执行部署脚本。具体操作见[步骤二：安装探针方式二，环境变量部署]。部署完成后执行cat \~/.llama-index-metrics/config.json确认otel段已写入。 **报错** **ModuleNotFoundError: opentelemetry.instrumentation** 启动应用时报错ModuleNotFoundError: No module named 'opentelemetry.instrumentation'，应用无法运行。 可以手动执行pip install opentelemetry-instrumentation opentelemetry-sdk opentelemetry-exporter-otlp补装依赖，或重新执行部署脚本。执行pip list \| grep opentelemetry确认依赖是否完整。 **交互式input卡死** 应用包含input()等交互式输入操作时，使用opentelemetry-instrument启动后终端无响应，无法输入。 改用sitecustomize.py方式启动（见[步骤三：启动应用] \> 方式二），不使用opentelemetry-instrument命令。sitecustomize方式通过Python模块加载机制初始化探针，不影响stdin处理。 **指标为空或为0** 应用已正常运行并产生调用，但AgentArts指标分析页面中某些指标值为空或显示为0。 1. 窗口内样本不足。AOM指标按时间窗口聚合，如果应用运行时间短或调用次数少，窗口内可能没有足够的样本数据。 2. resource_type不匹配。创建智能体时选择的类型（agent/multiagents/workflow）必须与部署脚本中--resource-type参数或config.json中resource_type字段的值一致，否则指标无法正确关联到智能体。 **RAG无conversation.id** 使用RAG（检索增强生成）场景时，调用链中会话Span缺少conversation.id属性，导致AgentArts会话分析页面无法关联该会话。 建议使用最新版本的探针whl包，通过pip show huaweicloud-opentelemetry-instrumentation-llama-index检查版本，如版本过旧请重新部署最新whl。 **重复部署不生效** 重新执行部署脚本安装新版探针后，应用行为未发生变化，仍在使用旧版本探针。 确认执行部署脚本时--whl参数指向的是最新的whl文件。部署完成后执行pip show huaweicloud-opentelemetry-instrumentation-llama-index检查版本号是否已更新。如果仍未生效，执行pip uninstall huaweicloud-opentelemetry-instrumentation-llama-index卸载旧版本后再重新部署。