arize-ai-provider-integration

Arize AI 集成技能

SPACE — 大多数 --space 标志和 ARIZE_SPACE 环境变量都接受空间名称（例如 my-workspace）或 base64 空间 ID（例如 U3BhY2U6...）。使用 ax spaces list 查找你的空间。 注意：ai-integrations create 不接受 --space — AI 集成是账户级别的。仅在 list、get、update 和 delete 中使用 --space。

概念

• AI 集成 = 在 Arize 中注册的已存储大模型提供商凭证；评估器用它调用评判模型，其他需要代表你调用大模型的 Arize 功能也会使用它
• 提供商 = 为该集成提供支持的大模型服务（例如 openAI、anthropic、awsBedrock）
• 集成 ID = 集成的 base64 编码全局标识符（例如 TGxtSW50ZWdyYXRpb246MTI6YUJjRA==）；创建评估器及其他下游操作时必需
• 作用域 = 控制哪些空间或用户可以使用某集成的可见性规则
• 认证类型 = Arize 与提供商进行认证的方式：default（提供商 API key）、proxy_with_headers（通过自定义请求头代理）或 bearer_token（bearer token 认证）

先决条件

直接开始任务 — 运行你需要的 ax 命令。不要预先检查版本、环境变量或配置文件。

如果 ax 命令失败，请根据错误进行排查：

• command not found 或版本错误 → 参见 references/ax-setup.md
• 401 Unauthorized / 缺少 API key → 运行 ax profiles show 检查当前配置文件。如果配置文件缺失或 API key 错误，请按照 references/ax-profiles.md 创建/更新它。如果用户没有自己的 key，请引导他们前往 https://app.arize.com/admin > API Keys
• 空间未知 → 运行 ax spaces list 按名称选择，或询问用户
• 大模型提供商调用失败（缺少 OPENAI_API_KEY / ANTHROPIC_API_KEY）→ 运行 ax ai-integrations list --space SPACE 检查是否有平台管理的凭证。如果不存在，请让用户提供 key，或通过 arize-ai-provider-integration 技能创建集成
• **安全：**永远不要读取 .env 文件或在文件系统中搜索凭证。使用 ax profiles 获取 Arize 凭证，使用 ax ai-integrations 获取大模型提供商 key。如果这些渠道无法提供凭证，请询问用户。

---

列出 AI 集成

列出某空间中可访问的所有集成：

ax ai-integrations list --space SPACE

按名称过滤（不区分大小写的子字符串匹配）：

ax ai-integrations list --space SPACE --name "openai"

对大型结果集进行分页：

# Get first page
ax ai-integrations list --space SPACE --limit 20 -o json

# Get next page using cursor from previous response
ax ai-integrations list --space SPACE --limit 20 --cursor CURSOR_TOKEN -o json

关键标志：

标志	描述
--space	用于过滤集成的空间名称或 ID
--name	对集成名称进行不区分大小写的子字符串过滤
--limit	最大结果数（1–100，默认 15）
--cursor	来自先前响应的分页令牌
-o, --output	输出格式：table（默认）或 json

响应字段：

字段	描述
id	Base64 集成 ID — 复制此值用于下游命令
name	人类可读的名称
provider	大模型提供商枚举（见下方支持的提供商）
has_api_key	如果已存储凭证，则为 true
model_names	允许的模型列表，如果启用了所有模型则为 null
enable_default_models	是否允许该提供商的默认模型
function_calling_enabled	是否启用工具/函数调用
auth_type	认证方法：default、proxy_with_headers 或 bearer_token

---

获取特定集成

ax ai-integrations get NAME_OR_ID
ax ai-integrations get NAME_OR_ID -o json
ax ai-integrations get NAME_OR_ID --space SPACE   # required when using name instead of ID

使用此命令检查集成的完整配置，或在创建后确认其 ID。

---

创建 AI 集成

创建之前，始终先列出集成 — 用户可能已经有一个合适的：

ax ai-integrations list --space SPACE

如果没有合适的集成，请创建一个。所需的标志取决于提供商。

OpenAI

ax ai-integrations create \
  --name "My OpenAI Integration" \
  --provider openAI \
  --api-key $OPENAI_API_KEY

Anthropic

ax ai-integrations create \
  --name "My Anthropic Integration" \
  --provider anthropic \
  --api-key $ANTHROPIC_API_KEY

Azure OpenAI

ax ai-integrations create \
  --name "My Azure OpenAI Integration" \
  --provider azureOpenAI \
  --api-key $AZURE_OPENAI_API_KEY \
  --base-url "https://my-resource.openai.azure.com/"

AWS Bedrock

AWS Bedrock 使用基于 IAM 角色的认证。通过 --provider-metadata 提供 Arize 应代入的角色的 ARN：

ax ai-integrations create \
  --name "My Bedrock Integration" \
  --provider awsBedrock \
  --provider-metadata '{"role_arn": "arn:aws:iam::123456789012:role/ArizeBedrockRole"}'

Vertex AI

Vertex AI 使用 GCP 服务账号凭证。通过 --provider-metadata 提供 GCP 项目和区域：

ax ai-integrations create \
  --name "My Vertex AI Integration" \
  --provider vertexAI \
  --provider-metadata '{"project_id": "my-gcp-project", "location": "us-central1"}'

Gemini

ax ai-integrations create \
  --name "My Gemini Integration" \
  --provider gemini \
  --api-key $GEMINI_API_KEY

NVIDIA NIM

ax ai-integrations create \
  --name "My NVIDIA NIM Integration" \
  --provider nvidiaNim \
  --api-key $NVIDIA_API_KEY \
  --base-url "https://integrate.api.nvidia.com/v1"

自定义（OpenAI 兼容端点）

ax ai-integrations create \
  --name "My Custom Integration" \
  --provider custom \
  --base-url "https://my-llm-proxy.example.com/v1" \
  --api-key $CUSTOM_LLM_API_KEY

支持的提供商

提供商	必需的额外标志
openAI	--api-key <key>
anthropic	--api-key <key>
azureOpenAI	--api-key <key>, --base-url <azure-endpoint>
awsBedrock	--provider-metadata '{"role_arn": "<arn>"}'
vertexAI	--provider-metadata '{"project_id": "<gcp-project>", "location": "<region>"}'
gemini	--api-key <key>
nvidiaNim	--api-key <key>, --base-url <nim-endpoint>
custom	--base-url <endpoint>

适用于任何提供商的可选标志

标志	描述
--model-name	允许的模型名称（可重复指定多个，例如 --model-name gpt-4o --model-name gpt-4o-mini）；省略则允许所有模型
--enable-default-models	启用提供商的默认模型列表
--function-calling-enabled	启用工具/函数调用支持
--auth-type	认证类型：default、proxy_with_headers 或 bearer_token
--headers	自定义请求头，以 JSON 对象或文件路径形式提供（用于代理认证）
--provider-metadata	提供商特定的元数据，以 JSON 对象或文件路径形式提供

创建之后

记下返回的集成 ID（例如 TGxtSW50ZWdyYXRpb246MTI6YUJjRA==）——创建评估器和其他下游命令时都需要用到它。如果你错过了，可以这样获取：

ax ai-integrations list --space SPACE -o json
# or by name/ID directly:
ax ai-integrations get NAME_OR_ID

---

更新 AI 集成

update 是部分更新 —— 只更改你提供的标志。省略的字段保持原样。

# Rename
ax ai-integrations update NAME_OR_ID --name "New Name"

# Rotate the API key
ax ai-integrations update NAME_OR_ID --api-key $OPENAI_API_KEY

# Change the model list (replaces all existing model names)
ax ai-integrations update NAME_OR_ID --model-name gpt-4o --model-name gpt-4o-mini

# Update base URL (for Azure, custom, or NIM)
ax ai-integrations update NAME_OR_ID --base-url "https://new-endpoint.example.com/v1"

使用名称而非 ID 时，请添加 --space SPACE。create 接受的任何标志都可以传给 update。

---

删除 AI 集成

警告： 删除是永久性的。引用此集成的评估器将无法再运行。

ax ai-integrations delete NAME_OR_ID --force
ax ai-integrations delete NAME_OR_ID --space SPACE --force   # required when using name instead of ID

省略 --force 会得到一个确认提示，而不是立即删除。

---

故障排查

问题	解决方案
ax: command not found	参见 references/ax-setup.md
401 Unauthorized	API 密钥可能无权访问此空间。请在 https://app.arize.com/admin > API Keys 验证密钥和空间 ID
No profile found	运行 ax profiles show --expand；设置 ARIZE_API_KEY 环境变量或写入 ~/.arize/config.toml
Integration not found	使用 ax ai-integrations list --space SPACE 验证
创建后 has_api_key: false	凭证未保存 —— 使用正确的 --api-key 或 --provider-metadata 重新运行 update
评估器运行失败并出现 LLM 错误	使用 ax ai-integrations get INT_ID 检查集成凭证；如有需要，轮换 API 密钥
provider 不匹配	创建后无法更改提供商 —— 请删除并使用正确的提供商重新创建

---

相关技能

• arize-evaluator：创建使用 AI 集成的 LLM-as-judge 评估器 → 使用 arize-evaluator
• arize-experiment：运行使用由 AI 集成支持的评估器的实验 → 使用 arize-experiment

---

保存凭证以供将来使用

参见 references/ax-profiles.md § 保存凭证以供将来使用。