arize-ai-provider-integration

Arize AI 集成技能

SPACE — --space 标志接受空间名称（例如 my-workspace）或 base64 空间ID（例如 U3BhY2U6...）。使用 ax spaces get NAME 解析已知名称；名称未知时，使用 ax spaces list 浏览。 注意：ai-integrations create 不接受 --space — AI 集成的作用范围是账户级别。仅将 --space 用于 list、get、update 和 delete。

概念

• AI 集成 = 在 Arize 中注册并保存的 LLM 提供商凭据；评估器会使用它调用裁判模型，Arize 中需要代表你调用 LLM 的其他功能也会使用它
• 提供商 = 为集成提供支持的 LLM 服务（例如 OPEN_AI、ANTHROPIC、AWS_BEDROCK）
• 集成 ID = 集成的 base64 编码全局标识符（例如 TGxtSW50ZWdyYXRpb246MTI6YUJjRA==）；创建评估器及执行其他下游操作时需要此 ID
• 作用范围 = 控制哪些空间或用户可以使用集成的可见性规则
• 身份验证类型 = Arize 与提供商进行身份验证的方式：DEFAULT（提供商 API 密钥）、PROXY_WITH_HEADERS（通过自定义标头使用代理）、BEARER_TOKEN（Bearer 令牌身份验证）或 OAUTH2_CLIENT_CREDENTIALS

前提条件

直接执行任务 — 运行所需的 ax 命令。请勿预先检查版本、环境变量或配置文件。

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

• command not found 或版本错误 → 参阅 references/ax-setup.md
• 401 Unauthorized / 缺少 API 密钥 → 运行 ax profiles show 查看当前配置文件。如果缺少配置文件或 API 密钥错误，请按照 references/ax-profiles.md 创建或更新配置文件。如果用户没有自己的密钥，请引导他们前往 https://app.arize.com/admin > API Keys
• 空间未知 → 参阅 空间
• LLM 提供商调用失败（缺少提供商凭据）→ 运行 ax ai-integrations list --space SPACE 检查是否存在平台管理的凭据。如果不存在：
  • 首选：从下方的“支持的提供商”中提供确切的 ax ai-integrations create 命令（引用 $OPENAI_API_KEY 之类的环境变量名称，绝不提供原始值）。请用户在自己的终端中导出提供商密钥并运行该命令 — 切勿将密钥粘贴到聊天中。除非该变量已在当前终端会话中导出，否则不要自行运行创建命令。
  • **Bedrock/Vertex：**使用 --provider-metadata，而不是 --api-key（参阅下方的“支持的提供商”）。
• **安全：**切勿读取 .env 文件或搜索文件系统中的凭据。例外：非机密的 ARIZE_SPACE_ID 行（参阅空间）。使用 ax profiles 管理 Arize 凭据，使用 ax ai-integrations 管理 LLM 提供商密钥。切勿要求用户在聊天中粘贴机密信息。有关缺失凭据的处理，请参阅 references/ax-profiles.md。

---

列出 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

运行 ax ai-integrations list --help 查看标志。当已知集成名称或 ID 时，请改用 ax ai-integrations get（见下文），不要分页浏览列表；list 用于浏览。

响应字段：

字段	描述
id	Base64 集成 ID — 在下游命令中使用时请复制此值
name	易于阅读的名称
provider	LLM 提供商枚举（参阅下方的“支持的提供商”）
has_api_key	如果已保存凭据，则为 true
model_names	允许使用的模型列表；如果允许使用所有模型，则为 null
enable_default_models	是否允许使用此提供商的默认模型
function_calling_enabled	是否启用工具/函数调用
auth_type	身份验证方式：DEFAULT、PROXY_WITH_HEADERS、BEARER_TOKEN 或 OAUTH2_CLIENT_CREDENTIALS

---

获取特定集成

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

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

每个创建命令都遵循以下格式；提供商专属标志请参阅下表：

ax ai-integrations create \
  --name "My OpenAI Integration" \
  --provider OPEN_AI \
  --api-key $OPENAI_API_KEY \
  --enable-default-models

除 LiteLLM、Fireworks AI 和 Together AI 外，每个集成都需要模型来源：传入 --enable-default-models（Arize 为该提供商提供的默认模型列表）和/或一个或多个 --model-name 标志。如果两者都未提供，服务端会拒绝创建，并返回 400: An integration must have at least one model available。

如需查看某个提供商的完整示例和说明（Bedrock/Vertex 元数据、基础 URL、应避免使用的标志），请仅打开下表 Details 列中对应的提供商文件。

支持的提供商

提供商	必需的额外标志（“模型来源” = --enable-default-models 或 --model-name）	密钥环境变量	详情
OPEN_AI	--api-key <key>、模型来源	$OPENAI_API_KEY	provider-openai.md
ANTHROPIC	--api-key <key>、模型来源	$ANTHROPIC_API_KEY	provider-anthropic.md
AZURE_OPEN_AI	--api-key <key>、--base-url <azure-endpoint>、--model-name <deployment>	$AZURE_OPENAI_API_KEY	provider-azure-openai.md
AWS_BEDROCK	--provider-metadata '{"role_arn": "<arn>"}'（无需 API 密钥）、模型来源	—	provider-aws-bedrock.md
VERTEX_AI	--provider-metadata '{"project_id": "<gcp-project>", "location": "<region>", "project_access_label": "<label>"}'（无需 API 密钥）、模型来源	—	provider-vertex-ai.md
GEMINI	--api-key <key>、模型来源	$GEMINI_API_KEY	provider-gemini.md
NVIDIA_NIM	模型来源；--api-key 和 --base-url 为可选项（默认：由 NVIDIA 托管）	$NVIDIA_API_KEY	provider-nvidia-nim.md
CUSTOM	--base-url <endpoint>、模型来源	$CUSTOM_LLM_API_KEY	provider-custom.md
LITELLM	--base-url <endpoint>、--api-key <key>	$LITELLM_API_KEY	provider-litellm.md
FIREWORKS	仅 --api-key <key>——不要使用 --base-url 或 --headers	$FIREWORKS_API_KEY	provider-fireworks.md
TOGETHER_AI	仅 --api-key <key>——不要使用 --base-url 或 --headers	$TOGETHER_API_KEY	provider-together-ai.md

运行 ax ai-integrations create --help 查看可选标志。如果提供商位于代理之后，请将 --headers 与 --auth-type PROXY_WITH_HEADERS 配合使用。

创建后

记录返回的集成 ID（例如 TGxtSW50ZWdyYXRpb246MTI6YUJjRA==）——创建评估器及运行其他后续命令时需要用到它。如果未记录，可通过以下命令获取：

ax ai-integrations get NAME_OR_ID --space SPACE -o json

---

更新 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"

# Restrict visibility to specific spaces (full replace — lists all spaces that should have access)
ax ai-integrations update NAME_OR_ID \
  --scopings '[{"space_id": "SPACE_GLOBAL_ID", "scoping_type": "include"}]'

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

--scopings 标志： 控制哪些空间可以使用此集成。接受一个 JSON 作用域规则数组。更新时会替换所有现有作用域。使用 ax spaces list -o json 查找空间全局 ID。

---

删除 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 integrations（大模型和 Agent 集成）

ax integrations 在一个分组中管理大模型和 Agent 集成（list、get、delete、create llm|agent、update llm|agent）。运行 ax integrations <sub> --help 查看可用标志。

• **选择创建命令：**对于 AZURE_OPEN_AI，或需要使用 --auth-type 时，请使用 ax ai-integrations create（上述示例）；ax integrations create llm 不支持这两种情况。当必须在创建时设置作用范围（--scopings）时，请使用 ax integrations create llm。
• create llm 的提供商标志有所不同：Bedrock 和 Vertex AI 使用专用标志，而非 --provider-metadata。运行 ax integrations create llm --help 查看各提供商对应的标志列表。
• **Agent 端点：**使用 ax integrations create agent 注册 Agent 端点；运行其 --help 查看可用标志。
• 提供商不可变：在 ax integrations update llm 中，提供商不可更改；如需更改，请删除后重新创建。
• --type：list 会返回合并后的所有类型；使用 --type LLM 或 --type AGENT 进行筛选。按名称执行 get 和 delete 时需要指定 --type，因为名称仅在各自类型内唯一；使用 ID 时则不需要。

---

故障排除

问题	解决方案
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 get NAME_OR_ID --space SPACE 检查名称或 ID；仅当需要查找正确名称时，才使用 ax ai-integrations list --space SPACE --name TEXT
创建后出现 has_api_key: false	凭据未保存——使用正确的 --api-key 或 --provider-metadata 重新运行 update
评估器运行因大模型错误而失败	使用 ax ai-integrations get INT_ID 检查集成凭据；如有需要，请轮换 API 密钥
使用 FIREWORKS 或 TOGETHER_AI 时出现 Invalid value for '--provider'	已安装的 ax CLI 版本早于对这些提供商的支持版本——请升级 ax CLI（参见 references/ax-setup.md）
An integration must have at least one model available	添加 --enable-default-models 或至少一个 --model-name（除 LiteLLM、Fireworks AI 和 Together AI 外，所有提供商都必须指定）
集成的 provider 不正确	ax ai-integrations update NAME_OR_ID --provider NEW_PROVIDER 可以更改提供商，但其他字段会保持原样——请在同一次调用中传入新提供商所需的标志（API 密钥、基础 URL、模型来源）。如果两个提供商所需的设置差异很大，删除后重新创建会更简洁

---

相关技能

• arize-evaluator：创建使用 AI 集成的大模型裁判评估器 → 使用 arize-evaluator
• arize-experiment：运行使用由 AI 集成支持的评估器的实验 → 使用 arize-experiment

---

保存凭据以供将来使用

请参阅 references/ax-profiles.md § 保存凭据以供将来使用。