Arize Skills：为AI编码助手注入LLM应用可观测性技能

1. 项目概述：为AI编码助手注入LLM应用可观测性技能

如果你正在用Cursor、Claude Code这类AI编码助手开发基于大语言模型的应用，那你肯定遇到过这样的场景：应用上线后，某个提示词（Prompt）的响应突然变慢，或者返回的内容质量飘忽不定。你隐约觉得是某个环节出了问题，可能是模型调用超时，也可能是上下文处理逻辑有缺陷，但面对海量的日志和分散的监控指标，你就像在迷宫里打转，很难快速定位到根因。传统的APM工具对LLM应用这种新型架构往往力不从心，它们能告诉你接口耗时，却无法告诉你为什么这次生成的内容跑偏了。

这正是Arize Skills要解决的问题。它不是一个独立的工具，而是一套专门为AI编码助手（或称“智能体”）设计的技能插件集。简单来说，它把Arize平台在LLM可观测性领域沉淀多年的最佳实践——包括链路追踪、实验分析、提示词优化等核心工作流——封装成了AI助手能直接理解和执行的“技能”。当你把Arize Skills安装到你的开发环境中，你的AI助手就瞬间获得了“透视”LLM应用内部运行状态的能力。你可以直接对它说：“帮我分析一下最近一小时trace里所有的错误”，或者“对比一下A/B测试中两个提示词版本的效果”，助手就能调用对应的技能，与Arize后端交互，把结构化的分析结果和 actionable 的建议呈现在你面前。

这套技能的核心价值在于，它极大地降低了LLM应用运维（LLMOps）的门槛。你不再需要手动去记复杂的axCLI命令参数，也不用操心如何把分散的追踪数据拼凑成完整的故事。Arize Skills把这些繁琐的、容易出错的步骤都编码成了标准化的技能，让AI助手成为你和复杂可观测性数据之间的智能桥梁。无论是为现有应用快速添加追踪埋点，还是基于生产数据优化提示词，你都可以用最自然的对话方式来完成。

2. 核心技能深度解析与适用场景

Arize Skills包含了一系列技能，覆盖了LLM应用生命周期的关键阶段。理解每个技能的设计意图和最佳使用场景，能让你在开发运维中事半功倍。

2.1 核心运维技能：arize-trace 与 arize-instrumentation

arize-trace和arize-instrumentation是使用频率最高、也最基础的两个技能，它们分别对应了“观测”和“埋点”这两个核心动作。

arize-trace：你的生产环境调试望远镜这个技能的本质是一个强大的Trace查询与分析器。当线上用户反馈“AI回答得不对”或者你发现P99延迟飙升时，arize-trace就是你排查问题的第一站。它允许你通过多种维度精准定位数据：

• 按Trace ID/Span ID查询：这是最精确的定位方式。当你从日志或错误报告中获得了一个具体的ID，用这个技能可以直接拉取该次请求的完整调用链，包括所有的LLM调用、函数执行、外部服务请求，以及它们之间的父子关系和耗时。
• 按Session ID查询：对于多轮对话应用，一个Session ID对应一次完整的用户会话。通过这个技能，你可以复现整个会话过程中所有LLM的交互序列，这对于理解对话逻辑漂移、上下文累积导致的问题至关重要。
• 按时间范围与属性过滤：你可以命令助手“导出过去15分钟内所有状态为错误的trace”，或者“找出所有调用了gpt-4模型且耗时超过10秒的span”。这种灵活的过滤能力，让你能从海量数据中快速聚焦到异常模式。

实操心得：不要只把它当成一个数据导出工具。结合AI助手的分析能力，你可以让它对导出的trace进行自动化的根因分析。例如，你可以要求助手：“用arize-trace找出最近一小时内最慢的5个trace，并总结它们慢的共性原因，比如是否都调用了某个特定的外部API，或者输入token数是否异常偏高。”

arize-instrumentation：一键式无侵入埋点为现有应用添加可观测性代码往往是件脏活累活，你需要识别代码中的LLM调用点，选择合适的SDK进行包装，还要确保上下文信息能正确传递。arize-instrumentation技能将这个过程自动化了，它采用了一个非常聪明的两阶段工作流：

1. 代码库分析阶段：AI助手会扫描你的项目目录，自动识别出你使用的LLM提供商（如OpenAI、Anthropic、Azure OpenAI）和Web框架（如FastAPI、Flask、Django）。这个阶段它只读不写，生成一份分析报告。
2. 埋点实施阶段：基于分析报告，助手会为你生成具体的代码修改方案。它会使用Arize的“Agent-Assisted Tracing”能力，自动插入正确的@trace装饰器或上下文管理器，并处理好诸如异步调用、嵌套span、自定义属性记录等细节。

这个技能最大的优点是“无侵入”和“按需配置”。它不会在你的代码里硬塞一个庞大的SDK，而是根据你的实际使用情况，引入最精简的instrumentor库（如arize-instrumentation-openai）。这意味着更小的依赖负担和更清晰的代码。

2.2 实验与评估技能：arize-experiment 与 arize-evaluator

当应用稳定运行后，下一步就是优化和迭代。arize-experiment和arize-evaluator这两个技能，将传统的A/B测试和效果评估流程带入了AI助手的对话界面。

arize-experiment：数据驱动的提示词竞技场它的核心功能是让你能基于真实的生产数据集，科学地对比不同提示词、不同模型甚至不同参数配置的效果。工作流程通常是：

1. 创建数据集：使用arize-dataset技能，从生产trace中采样一批有代表性的输入数据（即用户的提问或指令），形成一个测试集。
2. 设计实验：定义你的实验组。例如，对照组使用当前的提示词V1，实验组A使用增加了思维链（Chain-of-Thought）的提示词V2，实验组B换用更便宜的模型gpt-3.5-turbo。
3. 运行与分析：技能会指挥你的应用代码（或一个测试脚本）对数据集中的每条输入，用不同的实验配置运行一遍，并将结果（输出、延迟、成本等）记录回Arize。
4. 决策支持：最后，你可以让助手帮你分析实验报告：哪个版本在关键指标（如回答准确性、用户满意度、成本）上综合表现最好？差异在统计上是否显著？

arize-evaluator：引入“AI裁判”进行自动化评估LLM输出的质量评估一直是个难题。arize-evaluator技能巧妙地运用了“LLM-as-a-Judge”的模式。你不需要手动为成千上万的输出打分，而是定义一个评估任务，让另一个LLM（裁判）根据规则来评分。 例如，你可以创建一个“事实一致性”评估器，裁判模型会对比LLM的回答和给定的参考知识源，判断是否存在事实矛盾。或者创建一个“有害内容”评估器，过滤掉不安全的输出。这个技能能帮你：

• 创建评估器：定义评估维度、评分标准（如1-5分）和裁判模型使用的提示词。
• 批量执行评估：对实验产生的输出，或任意一批生产数据，自动调用裁判模型进行打分。
• 设置监控：可以将评估器设置为持续运行，对流入生产环境的所有trace自动评分，一旦平均分低于阈值就触发告警。

注意事项：使用“AI裁判”时，裁判模型本身也存在偏见和不确定性。最佳实践是，对于非常关键的评估维度（如安全性、法律合规性），应采用“AI裁判初筛 + 人工抽样复核”的混合模式。同时，定期用一批标准测试题来校准你的评估器，确保其评分标准的一致性。

2.3 数据与集成管理技能

arize-dataset：管理你的黄金测试集数据集是实验和评估的基石。这个技能让你可以像管理代码一样管理你的测试数据集：创建、查看、更新、下载。一个高级用法是建立“黄金数据集”（Golden Dataset），即一组覆盖了核心用户场景、且有标准预期输出的测试用例。每次对提示词或模型进行重大变更前，都先在黄金数据集上跑一遍，确保核心能力没有回退。

arize-ai-provider-integration：集中管理模型密钥当你的应用需要调用多个AI提供商（OpenAI, Anthropic, Azure, Bedrock等）的模型时，密钥管理会很麻烦。这个技能允许你在Arize平台统一创建和管理这些供应商的凭证。之后，在你的应用代码或实验配置中，你可以通过引用Arize中的凭证ID来使用，避免了在代码或环境变量中硬编码敏感密钥，提升了安全性也便于轮换。

arize-annotation：为数据打上业务标签追踪数据本身是技术性的（耗时、状态码），而业务标签（如“用户类型：VIP”、“问题类别：售后咨询”）能让你从业务视角切片分析数据。这个技能让你可以定义标签配置，并可以通过Python SDK批量地为历史或实时的span数据打上标签。例如，你可以标记出所有“投诉类”对话，然后专门分析这类对话的响应质量和用户满意度。

arize-prompt-optimization：基于数据的提示词调优这是最具“智能”的技能之一。它不止是运行实验，而是能分析trace数据，自动发现提示词的薄弱环节，并尝试生成改进建议。例如，它可能发现当用户问题包含特定专业术语时，回答质量会下降，从而建议你在提示词中增加对该术语的解释指令。它结合了元提示（Meta-prompting）和实验技术，将提示词工程从“玄学”向“科学”推进了一步。

arize-link：快速跳转可视化界面虽然AI助手能在终端给出分析，但复杂的多维下钻分析还是在大屏上更直观。这个技能可以为你关心的trace、span或session生成一个直达Arize平台对应详情页的深度链接。一键点击，就能从对话式分析无缝切换到强大的可视化仪表盘。

3. 从零开始的完整安装与配置实战

了解了技能全景后，我们进入实战环节。我将以最常用的npx安装方式和axCLI配置文件认证为例，演示一个完整的、可复现的配置流程。假设我们正在开发一个基于FastAPI和OpenAI的智能客服应用。

3.1 环境准备与技能安装

首先，确保你的开发机上已经安装了Node.js（npx需要）和Python（axCLI基于Python）。然后，在你的项目根目录下打开终端。

步骤一：交互式安装技能运行以下命令，启动交互式安装向导：

npx skills add Arize-ai/arize-skills

这时，安装脚本会启动并询问你几个问题：

1. 检测到的AI助手：脚本会自动扫描你的系统，发现我安装了Cursor和Claude Code，并列出它们让我选择。我按空格键同时选中了这两个。
2. 选择安装范围：它问我“Install skills globally or for a specific project?”。我选择“Project”，并输入当前项目的路径/Users/me/my-ai-support-app。全局安装（~/.cursor/skills/）适用于所有项目，但项目级安装更干净，依赖隔离更好。
3. 选择技能：它列出了所有可用的技能。对于初次使用，我建议全选（按a键），然后按回车确认。后续如果需要精简，可以用--skill参数指定。
4. 安装axCLI：脚本检测到我没有安装ax命令行工具，会询问是否安装。选择“Yes”。它会推荐使用uv或pipx这种隔离环境工具来安装，以避免污染全局Python环境。我选择uv。

安装过程完成后，你会看到类似“Skills successfully symlinked to /Users/me/my-ai-support-app/.cursor/skills”的提示。这意味着技能文件已经以符号链接的形式安装到了你的项目下，AI助手启动时可以加载它们。

步骤二：验证技能加载打开你的AI助手（例如Cursor），新建一个聊天窗口。尝试输入一个与技能相关的指令，比如：

帮我列出可用的Arize相关技能。

如果安装成功，助手应该能识别出arize-trace等技能，并可能给出简要说明。这表明技能插件已成功激活。

3.2 认证配置详解与最佳实践

技能本身不存储密钥，它们依赖axCLI与Arize后端通信。因此，配置好axCLI的认证是关键一步。我强烈推荐使用ax profiles配置文件方式，它比环境变量更安全、更易于管理多环境。

步骤一：获取Arize API Key和Space ID

1. 登录 Arize平台 。
2. 点击右上角头像，进入“Admin” -> “API Keys”，创建一个新的API Key，并复制保存。这个Key就像你的个人密码。
3. 在平台首页或左侧菜单，找到你的Space（工作空间）。每个Space通常对应一个项目或环境（如生产、测试）。运行以下命令获取Space的标识符：

   ax spaces list -o json

   在输出中，找到对应的Space，记录下它的name（字符串）或id（一个base64编码的字符串）。两者任选其一即可。

步骤二：创建并激活CLI配置Profile现在，我们在终端里创建profile。推荐使用交互式向导，它能避免参数错误：

ax profiles create

按照提示依次输入：

• Profile name:prod(我给生产环境起名prod，你也可以用default)
• API key:粘贴你刚才复制的API Key。
• Space:输入你记录的Space name或ID。
• 其他设置（如region）：直接按回车使用默认值。

完成后，这个名为prod的profile就保存到了你的本地配置文件（通常是~/.config/arize/profiles.toml）中。你可以通过以下命令管理profile：

ax profiles list # 列出所有profile ax profiles use prod # 切换到`prod` profile ax profiles show # 查看当前活跃profile的详情

步骤三：设置环境变量（可选但推荐）虽然profile已经配置了Space，但有些技能或工具可能仍会读取ARIZE_SPACE环境变量。为了确保万无一失，可以将其添加到你的shell配置文件中：

# 如果你用的是zsh（macOS新系统默认） echo 'export ARIZE_SPACE="你的Space名称或ID"' >> ~/.zshrc # 如果你用的是bash echo 'export ARIZE_SPACE="你的Space名称或ID"' >> ~/.bashrc # 然后重载配置 source ~/.zshrc # 或 source ~/.bashrc

步骤四：完整验证运行一个综合验证命令，确保一切就绪：

ax --version && ax profiles show 2>&1 && ax spaces list --limit 1

这个命令会依次检查：1)axCLI版本是否正常；2) 当前活跃的profile信息是否正确显示；3) 是否能成功列出Space（只列一个作为测试）。如果每一步都成功返回信息，恭喜你，认证配置全部完成。

安全警告：绝对不要将你的profiles.toml文件或任何包含API Key的文件提交到Git仓库。该文件默认保存在用户目录下，是个人本地配置。团队共享配置时，应通过文档分享Space ID，让每位成员用自己的API Key创建各自的profile。

3.3 为现有应用快速添加追踪埋点

现在，假设我们有一个已经写好的FastAPI应用，但还没有任何追踪代码。我们将使用arize-instrumentation技能，让AI助手帮我们自动完成埋点。

步骤一：启动技能并分析代码库在AI助手（如Cursor）中，输入以下指令：

请使用arize-instrumentation技能，为我的项目添加Arize追踪。

助手会激活该技能，并开始询问或执行：

1. 确认项目路径：它通常会确认当前所在目录就是你的项目根目录。
2. 开始代码分析：助手会扫描项目中的requirements.txt、pyproject.toml以及主要的.py文件，寻找LLM SDK（如openai,anthropic）和Web框架（fastapi,flask）的导入和使用痕迹。
3. 生成分析报告：扫描完成后，它会生成一份报告，类似：

   分析完成： - 检测到 LLM 提供商: openai (v1.0+) - 检测到 Web 框架: fastapi - 主要入口文件: main.py - 建议安装的 instrumentor 包: arize-instrumentation-openai

步骤二：审查并实施修改方案接着，助手会基于分析报告，提出具体的代码修改方案。它可能会展示一个diff预览，例如在main.py中：

# 原代码 from openai import OpenAI client = OpenAI() async def chat_endpoint(query: str): response = client.chat.completions.create( model="gpt-4", messages=[{"role": "user", "content": query}] ) return response.choices[0].message.content # 助手建议的修改后代码 from openai import OpenAI from arize_instrumentation import trace # 自动添加的导入 from arize_instrumentation.openai import OpenAIInstrumentor client = OpenAI() OpenAIInstrumentor().instrument(client) # 自动添加的instrumentation行 @trace(name="chat_endpoint") # 自动添加的装饰器 async def chat_endpoint(query: str): response = client.chat.completions.create( model="gpt-4", messages=[{"role": "user", "content": query}] ) return response.choices[0].message.content

你需要仔细审查这些修改：装饰器添加的位置是否合适？instrumentor是否在客户端初始化后立即调用？确认无误后，授权助手应用这些更改。

步骤三：安装依赖并测试助手会提示你需要安装新的Python包：

pip install arize-instrumentation-openai

安装完成后，运行你的应用，并发送几个测试请求。然后，回到AI助手，使用另一个技能进行验证：

使用arize-trace技能，导出最近5分钟的trace，看看有没有我们刚发送的请求。

如果配置正确，你应该能看到刚刚的请求详情，包括span名称、耗时和状态。至此，你的应用就具备了完整的可观测性能力。

4. 高级使用技巧与常见问题排查

掌握了基本操作后，我们来看看如何高效利用这些技能，以及如何解决可能遇到的问题。

4.1 技能组合使用：构建诊断工作流

真正的威力在于将多个技能串联起来，形成一个自动化诊断或优化的工作流。你可以给AI助手一个复杂的指令，让它自主执行多步操作。

场景示例：自动诊断响应延迟问题你可以对助手说：

我注意到 /v1/chat 接口最近P95延迟很高。请执行以下操作： 1. 使用 `arize-trace` 技能，导出过去30分钟内该接口最慢的10条trace。 2. 分析这些trace，找出共同的慢速span（比如是某个特定的外部API调用，还是LLM生成本身慢）。 3. 如果慢的是LLM生成，再用 `arize-dataset` 从这些trace中提取用户输入，创建一个数据集。 4. 最后，用 `arize-prompt-optimization` 技能，基于这个数据集分析当前提示词，并提出优化建议来减少延迟。

一个有经验的AI助手在加载了这些技能后，能够理解这个多步任务，并依次调用相应的技能，最终给你一个结构化的分析报告和优化建议。这相当于你拥有一个24小时在线的初级LLMOps工程师。

4.2 权限管理与安全配置

安全是重中之重，尤其是在让AI助手执行涉及生产数据的操作时。

.claude/settings.json的配置（针对Claude Code）Arize Skills的测试工具和某些高级模式可能会请求bypassPermissions，这能跳过确认弹窗，但也带来了风险。你必须配置权限黑名单（denylist）来限制助手能执行的系统命令。在你的项目根目录或arize-skills仓库根目录下，创建或编辑.claude/settings.json文件，内容至少应包括：

{ "permissions": { "deny": [ "Bash(rm -rf *)", "Bash(curl *)", "Bash(wget *)", "Bash(ssh *)", "Bash(scp *)", "Bash(git push *)", "Bash(sudo *)", "Bash(chmod *)", "Bash(chown *)", "Bash(* > /dev/*)", "Bash(echo * > /etc/*)", "Bash(* | bash)", "Bash(* | sh)" ] } }

这个黑名单禁止了删除根目录、远程下载执行、特权操作、管道攻击等危险命令。这是一个基础的安全护栏，你应该根据自己项目的实际情况进行增补。

API Key的最小权限原则在Arize平台创建API Key时，尽量遵循最小权限原则。如果这个Key只用于从开发环境查询数据，那么在创建时就可以只勾选read:trace,read:dataset等读取权限，不要赋予write或admin权限。这样即使Key意外泄露，影响范围也是可控的。

4.3 常见问题与解决方案速查表

在实际使用中，你可能会遇到一些典型问题。下表汇总了常见症状、可能原因和解决方法：

4.4 性能优化与成本控制

当数据量变大后，你需要关注技能使用的效率和成本。

查询性能优化使用arize-trace导出数据时，尽量使用最精确的过滤器。避免使用过于宽泛的时间范围（如“过去一周”），而是结合Trace ID、Span名称、属性（attributes.llm.model="gpt-4"）来缩小查询范围。对于定期分析任务，可以考虑先用技能导出元数据ID，再用Arize的Python SDK进行批量异步处理。

实验成本控制运行arize-experiment会真实调用LLM API，产生费用。在实验设计阶段，务必：

1. 使用小型代表性数据集：先用100-200条数据跑出趋势，再决定是否扩展到全量。
2. 设置预算和熔断：在实验配置中，可以设定最大调用次数或总成本上限。
3. 利用缓存：对于相同的输入和配置，确保实验框架支持结果缓存，避免重复计算。

数据保留策略与Arize平台配合，设置合理的数据保留周期。对于调试用的trace数据，保留7-30天可能就够了；对于用于模型再训练的高质量输入输出对，可以永久保留或导出到廉价存储。定期清理过期数据，能保持技能查询的响应速度。