更新时间:2026-11-04 GMT+08:00
分享

LlamaIndex框架

观测功能支持通过Python探针对LlamaIndex智能体进行观测,Python探针是华为云AgentArts产品自研的Python语言的可观测采集探针,其基于OpenTelemetry标准实现了自动化埋点能力。

本章节针对使用LlamaIndex框架开发的第三方智能体应用,通过Python探针实现自动化埋点和数据上报。

前提条件

  • Python 环境版本 >= 3.9
  • LlamaIndex版本 >= 0.10.0。

探针初始化需要在应用启动时完成,建议在导入LlamaIndex模块之前初始化。

  • 在AgentArts观测界面查看数据不收费。
  • 但数据上报会产生费用:
    • 调用链上报到APM(应用性能管理服务),费用明细请参考APM计费说明。
    • 指标上报到AOM(应用运维管理服务),费用明细请参考AOM计费说明。
  • 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

探针文件(Python wheel安装包,用于pip安装)

install.py

一键部署脚本(跨平台,Windows/Linux通用)

install_env.ps1

环境变量部署脚本(Windows用)

install_env.sh

环境变量部署脚本(Linux用)

上表中的文件名含通配符*,实际下载的文件会包含具体版本号,部署时请使用实际文件名。

下载完成后,建议将文件统一放在一个目录中(如llama_probe_verify/),后续操作均在该目录下执行。

接入步骤

步骤一:获取接入参数

  1. 登录AgentArts 智能体平台。
  2. 在左侧导航栏选择“观测与优化 > 观测”。
  3. 在“智能体列表”页面,单击“接入智能体”,按照页面指引填写名称、智能体类型,创建一个“LlamaIndex”框架的智能体,并获取各配置参数。

    图1 获取配置参数

步骤二:安装探针方式一,一键部署

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 <Agent_ID> --domain-id <Domain_ID> --project-id <Project_ID> --endpoint <APM_Endpoint:4317> --token <APM_Token> --aom-endpoint <AOM_Endpoint:4317> --aom-access-code <AOM_Access_Code> --aom-prometheus-id <Prometheus_ID> --resource-type agent

    *_opentelemetry_instrumentation_llama_index-*.whl为通配符,实际使用时替换为真实的whl文件名。

    表2 install.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 <Agent_ID> \
      --domain-id <Domain_ID> \
      --project-id <Project_ID> \
      --endpoint <APM_Endpoint:4317> \
      --token <APM_Token> \
      --aom-endpoint <AOM_Endpoint:4317> \
      --aom-access-code <AOM_Access_Code> \
      --aom-prometheus-id <Prometheus_ID> \
      --resource-type agent

    *_opentelemetry_instrumentation_llama_index-*.whl为通配符,实际使用时替换为真实的whl文件名。

    首次执行后install.py自动获得+x权限,后续可直接./install.py运行。

    表3 install.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,执行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="<Domain_ID>"
    $env:agentarts_project_id="<Project_ID>"
    $env:agent_resource_id="<Agent_ID>"
    $env:resource_type="agent"
    
    $env:agentarts_agentops_apm_token="<APM_Token>"
    $env:agentarts_agentops_apm_exporter_endpoint="<APM_Endpoint:4317>"
    
    $env:agentarts_agentops_aom_access_code="<AOM_Access_Code>"
    $env:agentarts_agentops_aom_exporter_endpoint="<AOM_Endpoint:4317>"
    $env:agentarts_agentops_aom_prometheus_id="<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=<Domain_ID>
    export agentarts_project_id=<Project_ID>
    export agent_resource_id=<Agent_ID>
    export resource_type=agent
    
    export agentarts_agentops_apm_token=<APM_Token>
    export agentarts_agentops_apm_exporter_endpoint=<APM_Endpoint:4317>
    
    export agentarts_agentops_aom_access_code=<AOM_Access_Code>
    export agentarts_agentops_aom_exporter_endpoint=<AOM_Endpoint:4317>
    export agentarts_agentops_aom_prometheus_id=<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智能体平台,在“观测与优化 > 观测”页面中找到已接入的智能体,查看各指标与会话数据。

配置参数说明

探针安装后,配置集中在~/.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服务控制台,创建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="<MODEL_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 智能体平台。
  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卸载旧版本后再重新部署。

相关文档