arize-admin

Arize 管理技能

以编程方式管理 Arize 用户、组织、空间、角色、权限和 API 密钥——这些是企业访问控制的基础构件。

权限要求： 大多数操作需要 org-admin 或 account-admin 权限。如果命令返回 403 Forbidden，则已通过身份验证的配置文件权限不足。

破坏性操作规则： 删除、撤销、移除或不可逆地修改资源的命令（delete、revoke、remove-user、unrestrict）必须在执行前获得用户明确确认。当用户要求你执行此类操作时：

1. 准确概述将要发生的事情（例如：“这将删除用户 [email protected]、连带撤销其 API 密钥，并移除其所有组织/空间成员身份和角色绑定。”）
2. 询问用户是否确认（使用 AskUserQuestion）。
3. 仅在用户确认后，使用 --force 运行命令以跳过 CLI 的交互式提示。

未先征得用户确认，绝不要运行带 --force 的破坏性命令。

适用场景

• 邀请用户加入账户，并将其分配到组织和空间
• 一条命令即可让用户离职并撤销其所有访问权限
• 为新团队办理入驻：创建空间、自定义角色、分配用户并生成服务密钥
• 为 SAML/SSO 属性映射创建自定义角色（需要稳定的角色 ID）
• 限制项目访问权限，使其仅对明确绑定的用户开放
• 为 CI/CD 流水线或多租户架构创建范围受限的服务密钥
• 轮换或撤销 API 密钥
• 在空间内创建或删除项目

提前询问

对于多步骤工作流，在运行任何 ax 命令前收集所有必需信息。使用 AskUserQuestion，避免在工作流中途反复询问。先获取实时数据（例如组织列表），以便向用户提供实际选项，而不是让用户回忆 ID。

为新团队办理入驻

1. 已知组织名称时，运行 ax organizations get NAME -o json；使用 ax organizations list -o json 将组织名称作为选项展示。
2. 使用 AskUserQuestion（一次调用，最多 4 个问题）收集：
   • 哪个组织？ — 将列表中的组织名称作为选项展示
   • 空间名称 — 新团队的空间名称
   • 团队成员 — 要邀请的成员姓名和邮箱（用户可通过“其他”填写；如果暂无成员，请询问）
   • 服务密钥？ — 是否为 CI/CD 流水线生成服务密钥

为用户办理离职

运行任何命令前先询问：

• 哪位用户？ — 邮箱地址（随后使用 ax users get EMAIL -o json 查询）

限制项目访问

运行任何命令前先询问：

• 哪个空间和项目？ — 用于查询项目全局 ID
• 哪些用户需要明确授权？ — 要绑定到受限项目的用户邮箱

邀请用户（单独操作）

运行任何命令前先询问：

• 姓名和邮箱 — 要邀请的每位用户的信息
• 角色 — ADMIN、MEMBER 或 ANNOTATOR（将其作为选项展示；账户级用户创建没有 READ_ONLY 角色）
• 邀请模式 — EMAIL_LINK、TEMPORARY_PASSWORD 或 NONE（必须提供 --invite-mode）

撤销或轮换 API 密钥

运行任何命令前先询问：

• 哪个密钥？ — 运行 ax api-keys list -o json，按名称和状态展示选项；或询问 KEY_ID
• 撤销还是轮换？ — revoke 会立即使密钥失效；refresh 会颁发一个范围相同的新密钥，并立即使旧密钥失效，除非传入 --grace-period-seconds

如果用户说要“删除” API 密钥，请使用 ax api-keys revoke 使其失效。

概念

• 组织 — 账户内的命名分组（例如，每个业务部门一个）。空间属于组织。用户先添加到账户，然后添加到组织，最后添加到空间。
• 空间 — 用于隔离跟踪记录、数据集和项目的工作区。用户必须先成为组织成员，才能添加到该组织中的空间。
• 角色 — 一组命名的权限。预定义角色由系统管理。自定义角色由管理员创建。组织/空间成员资格的角色（ADMIN、MEMBER、READ_ONLY、ANNOTATOR）与通过 ax role-bindings 使用的自定义 RBAC 角色相互独立。
• 角色绑定 — 将自定义角色细粒度地分配给用户，使其在特定资源（空间或项目）上生效。
• 资源限制 — 将项目标记为受限，使其仅可由在该项目上拥有显式角色绑定的用户访问。任何更高层级（空间、组织、账户）绑定的角色均不适用。
• API 密钥 — 可以是 用户 密钥（以创建者身份进行身份验证，拥有完整用户权限），也可以是 服务 密钥（限定到特定空间，用于自动化流水线）。

先决条件

直接运行所需的 ax 命令。请勿预先检查版本或配置文件。

如果 ax 命令失败：

• 出现 command not found 或版本错误 → 请参阅 references/ax-setup.md
• 出现 401 Unauthorized / 缺少 API 密钥 → 运行 ax profiles show；按照 references/ax-profiles.md 中的说明操作
• 出现 403 Forbidden → 当前配置文件缺少管理员权限；请参阅 references/ax-profiles.md（绝不要让用户在聊天中粘贴管理员密钥）
• **安全性：**绝不要读取 .env 文件或搜索文件系统以查找凭据。例外：非机密的 ARIZE_SPACE_ID 行（参见 空间）。使用 ax profiles 管理 Arize 凭据。绝不要让用户在聊天中粘贴机密信息。绝不要回显、记录或显示原始 API 密钥值。如缺少凭据，请参阅 references/ax-profiles.md。

**OAuth 登录选项：**用户可以运行 ax auth login，通过基于浏览器的 OAuth PKCE 进行身份验证，而非使用 API 密钥（之后运行 ax auth logout 即可撤销）。当前配置文件必须是 OAuth 配置文件，并通过 ax profiles create --auth-method oauth 创建。如果用户询问其他身份验证方式，请告知此选项——请勿自行运行 ax auth login，因为该命令会以交互方式打开浏览器。

---

用户

用户必须先存在于账户中，才能添加到组织或空间。账户级角色：ADMIN、MEMBER、ANNOTATOR

ax users list                                  # all users
ax users list --email "jane"                   # substring filter
ax users list --status ACTIVE                  # ACTIVE or INVITED
ax users list -l 100 -o json                   # paginate, get global IDs

ax users get USER_ID_OR_EMAIL                   # direct lookup; list is for browsing

ax users create \
  --full-name "Jane Doe" \
  --email [email protected] \
  --role MEMBER \
  --invite-mode EMAIL_LINK        # or: NONE | TEMPORARY_PASSWORD

ax users update USER_ID --full-name "Jane Smith"
ax users update USER_ID --is-developer          # grant developer flag

ax users delete --id USER_ID --force   # ⚠ confirm first — cascades: org/space memberships, API key revocation, role bindings
ax users delete --email [email protected] --force   # or resolve by email instead of ID

ax users resend-invitation USER_ID
ax users reset-password USER_ID

---

组织

组织角色：ADMIN、MEMBER、READ_ONLY、ANNOTATOR

ax organizations list
ax organizations list --name "platform"
ax organizations list -l 100 -o json

ax organizations get "Platform Team"

ax organizations create --name "Platform Team" --description "Core ML platform"

ax organizations update "Platform Team" --name "ML Platform" --description "Updated"

# Add user (must exist in account first)
ax organizations add-user "Platform Team" --user-id USER_ID --role MEMBER

# Remove user (also removes from all child spaces) — ⚠ confirm first
ax organizations remove-user "Platform Team" --user-id USER_ID --force

# Delete organization: ⚠ irreversible; deletes org and all resources inside (spaces, projects, experiments, datasets)
ax organizations delete "Platform Team" --force

---

空间

空间角色：ADMIN、MEMBER、READ_ONLY、ANNOTATOR

ax spaces list
ax spaces list --organization-id ORG_ID

ax spaces get "my-workspace"

# --organization-id required; get ORG_ID from ax organizations list -o json
ax spaces create --name "team-alpha" --organization-id ORG_ID

ax spaces update "team-alpha" --name "team-alpha-v2"

ax spaces delete "team-alpha" --force   # ⚠ confirm first — irreversible; deletes all resources

# User must be an org member before being added to a space
ax spaces add-user "team-alpha" --user-id USER_ID --role MEMBER
ax spaces remove-user "team-alpha" --user-id USER_ID --force   # ⚠ confirm first

---

角色

通过 ax role-bindings 使用的自定义 RBAC 角色。它们与组织/空间成员资格中的简单角色 ADMIN、MEMBER、READ_ONLY、ANNOTATOR 相互独立。

ax roles list                          # all roles
ax roles list --is-custom -o json      # custom only — get stable IDs for SAML mappings
ax roles list --is-predefined

ax roles get "Data Scientist"          # inspect permissions

# --permissions is comma-separated; fully replaces on update
ax roles create \
  --name "Data Scientist" \
  --permissions "PROJECT_READ,DATASET_CREATE,EXPERIMENT_CREATE" \
  --description "Read traces, create datasets and experiments"

ax roles update "Data Scientist" --permissions "PROJECT_READ,DATASET_CREATE,EXPERIMENT_CREATE,EVALUATOR_CREATE"

ax roles delete "Data Scientist" --force   # ⚠ confirm first — predefined roles cannot be deleted

**查找可用权限：**对系统角色（例如 Member、Admin）运行 ax roles get <predefined-role> -o json，即可查看有效的权限名称。

---

角色绑定

将自定义角色细粒度地分配给用户，使其在特定资源（空间或项目）上生效。

# Assign at space level
ax role-bindings create \
  --user-id USER_GLOBAL_ID \
  --role-id ROLE_GLOBAL_ID \
  --resource-type SPACE \
  --resource-id SPACE_GLOBAL_ID

# Assign at project level
ax role-bindings create \
  --user-id USER_GLOBAL_ID \
  --role-id ROLE_GLOBAL_ID \
  --resource-type PROJECT \
  --resource-id PROJECT_GLOBAL_ID

ax role-bindings get BINDING_ID
ax role-bindings update BINDING_ID --role-id NEW_ROLE_ID
ax role-bindings delete BINDING_ID --force   # ⚠ confirm first

# List bindings for a resource type (--resource-type is required)
ax role-bindings list --resource-type SPACE
ax role-bindings list --resource-type PROJECT --user-id USER_GLOBAL_ID -o json

此操作具有幂等性——如果用户在该资源上已有绑定，则不报错并直接退出。

---

资源限制

限制项目、仪表板或提示词的访问权限，使其仅可由在该资源上拥有显式角色绑定的用户访问。空间/组织级角色不适用。

ax resource-restrictions list                                          # all restrictions, paginated
ax resource-restrictions list --resource-type DASHBOARD                # filter to one resource type (PROJECT, DASHBOARD, or PROMPT)
ax resource-restrictions list --limit 50 --cursor PAGINATION_CURSOR    # fetch next page

ax resource-restrictions restrict --resource-id RESOURCE_GLOBAL_ID     # idempotent
ax resource-restrictions unrestrict --resource-id RESOURCE_GLOBAL_ID --force   # ⚠ confirm first

# Finding a project ID
ax projects get NAME --space "my-workspace" -o json

---

API 密钥

范围：ax api-keys list 仅返回已通过身份验证的用户所拥有的密钥。如需进行组织范围的审计，请使用 Arize UI（Settings > API Keys）。

ax api-keys list
ax api-keys list --key-type SERVICE --status ACTIVE -o json

# User key — authenticates as creator, inherits their full permissions
ax api-keys create --name "CI pipeline" --expires-at "2027-01-01T00:00:00"

# Service key — bot user scoped to org(s)/space(s) via --assignments JSON
# (recommended for CI/CD pipelines; get ORG_ID from `ax organizations list -o json`)
ax api-keys create-service-key \
  --name "team-alpha-traces" \
  --assignments '[{"org_id": "ORG_ID", "spaces": [{"space": "team-alpha"}]}]' \
  --expires-at "2027-01-01T00:00:00"

ax api-keys revoke KEY_ID --force   # ⚠ confirm first — invalidates the key immediately

# Rotation — issues a new key with same scope; old key dies immediately
# unless --grace-period-seconds keeps it valid while clients switch over
ax api-keys refresh KEY_ID --grace-period-seconds 3600
ax api-keys refresh KEY_ID --expires-at "2028-01-01T00:00:00"

**原始密钥只会显示一次。**请立即将其保存到密钥管理器中。之后无法再次检索。

create-service-key 的范围完全通过 --assignments 指定；运行 ax api-keys create-service-key --help 查看分配 JSON 格式、默认角色和 --account-role。传入 --env-file PATH，将新密钥写入 dotenv 或 .envrc 文件中的 ARIZE_API_KEY，这样密钥会保存到文件中，而不是出现在对话里。

---

项目

项目位于空间中，包含跟踪记录、数据集和实验。

ax projects list --space SPACE
ax projects list --space SPACE --name "playground"   # substring filter
ax projects list --space SPACE -l 100 -o json        # get base64 IDs

ax projects get NAME_OR_ID --space SPACE

ax projects create --name "my-project" --space SPACE

ax projects update NAME_OR_ID --name "new-project-name" --space SPACE

ax projects delete NAME_OR_ID --space SPACE --force   # ⚠ confirm first — deletes all traces and datasets

注意：ax spans export、ax traces export 和 ax resource-restrictions 使用项目 ID（base64 字符串）。如果命令不接受项目名称，请从 ax projects get NAME --space SPACE -o json 的输出中获取 id 字段；ax projects list 用于浏览。

---

企业工作流与故障排查

分步工作流（为团队办理入驻、SAML/SSO 映射、项目限制、离职处理、多租户密钥）和故障排查表见 references/REFERENCE.md。

---

相关技能

• arize-instrumentation：空间准备就绪后，在 LLM 应用中设置跟踪。
• arize-trace：在受管理的空间中导出并检查跟踪记录。
• arize-dataset：在空间中创建和管理数据集。