MCP 工具参考

HyperAI MCP 服务器提供 58 个工具,分为六个功能组。所有工具在 OAuth 登录后以你自己的账号身份执行,结果仅限于你有权访问的容器、项目与数据集。列表类工具每页返回 30 条。

通常你不需要直接调用这些工具——AI 助手会根据你的要求自行选择。本页作为参考,帮助你了解助手能做什么、不能做什么。

写操作前的确认Copy Anchor Link

助手不会静默执行写操作。在创建容器(compute_create_job)、重启容器(compute_restart_workspace)、创建项目(compute_create_project)、创建数据集条目或版本(dataset_create、dataset_create_version)、修改项目或数据集的可见范围(compute_update_project_permissions、dataset_update_permissions),以及部署、重启、扩缩容或停止模型服务(serving_create、serving_create_version、serving_restart_version、serving_update_version、serving_stop_version)之前,它会先复述即将执行的内容——包括计费后果——并等待你的明确同意,即使资源是你自己点名的。签发个人访问令牌(user_create_personal_access_token),以及删除数据集(dataset_delete)、模型服务版本(serving_delete_version)、整个模型服务(serving_delete)、容器运行记录(compute_delete_job)或项目(compute_delete_project)需要你对具体取值的明确批准;这些事助手不会在"你决定就行"的授权下执行。在批量或"一口气跑完别打扰我"的流程里,助手不会把删除放进流程,而是改用停止容器或停止服务版本等可逆动作——除非你明确点名要删某个资源。

User(账户)Copy Anchor Link

用于查询自己账户的工具——档案、配额、账单、用量与订阅,以及管理个人访问令牌。这些工具始终作用于当前登录账号,不接受 username 参数。

user_get_profileCopy Anchor Link

获取你的账户档案：用户名、显示名称、邮箱、注册时间、角色、会员状态、余额,以及所属组织。组织的 ID(而非显示名称)即 compute 与 dataset 工具中 username 参数可接受的值——既可用于列出组织资源(如 compute_list_jobs),也可用于在组织名下创建与管理资源(如 compute_create_job)。可用于验证连接。组织的能力标志、席位配额与成员列表请使用 org_get 与 org_list_members 工具查询。

无参数。

user_get_quotaCopy Anchor Link

获取你的存储配额(已用 / 总量 / 剩余)、各资源型号的预付算力时长,以及账户限制(如每种资源与 GPU 类型同时能开几个容器,以及数据集、项目的数量上限)。

三个概念容易混淆。余额是钱(见 user_get_profile);配额是预付的订阅时长与存储余量(本工具);限制是并发与数量上限(本工具)。某个资源的剩余时长为 0 本身不构成阻碍——它只表示订阅时长用完了,只要余额足以承担该资源,按量付费仍会从余额扣费。容器能否真正启动,由 compute_create_job 在创建时的检查决定(资源可负担、集群容量、每资源并发上限、运行时、项目、计费方案);配额从不在其中——唯一的例外是存储：存储剩余为 0 时创建容器会失败并报「无存储额度」,不会创建任何东西。查询不受影响,助手仍能报出你的余额与配额。若存储总量为 0,只有增加额度才有用(删数据释放不了空间);总量不为 0 时,删除数据集、版本或容器可以释放空间。

无参数。

user_list_transactionsCopy Anchor Link

列出账单流水——充值、扣费、订阅续费、退款与转账,按时间从新到旧排序。每笔金额都带有各自的币种。

参数：

• type — 按方向筛选：recharge(充值、赠送、代金券入账)、spend(扣费)、refund(退款)、transfer(账户间转账)或 all(默认)
• page — 页码

user_list_usagesCopy Anchor Link

列出资源使用记录,按时间从新到旧排序。计算类记录带有使用时长;serving 类记录按(结束时间 − 开始时间)× 副本数计费;存储类记录带有计入存储配额的容量变化。

参数：

• page — 页码

user_list_subscriptionsCopy Anchor Link

列出你所有类别的订阅——会员、存储扩容、预付算力、一次性永久算力与组织席位,含套餐、每周期价格、有效期与自动续费状态。处于生效中且开启自动续费的订阅会在每个周期结束时自动扣费。

取消订阅只能在 HyperAI 控制台操作,本工具不支持。

无参数。

user_get_spend_analysis_guideCopy Anchor Link

返回账户消费分析指南。助手在回答消费类问题("余额为什么变少了"、"我的钱花在哪了")前应先阅读该指南,以便先通过其他账户工具收集完整数据。

无参数。

user_list_personal_access_tokensCopy Anchor Link

列出你的个人访问令牌(PAT)——长期有效的 API 凭据,含名称、创建与过期时间、最近使用时间。列表中永远不包含令牌明文：明文只在创建令牌时显示一次。空列表并不代表从未创建过令牌(已吊销的令牌会被隐藏);列表中的令牌也不一定可用——过期令牌仍会留在列表里,请自行核对 expiresAt。

无参数。

user_create_personal_access_tokenCopy Anchor Link

为你自己的账号创建个人访问令牌。PAT 不受改密码或退出登录的影响,只有被吊销或过期后才会失效。

签发令牌属于审批档操作：PAT 等同于账号密码,因此助手会先复述令牌名称与过期时间——将要传入的 expires_at,或省略时的默认 90 天——并等待你的明确批准后再调用。它不会在"你决定就行"的授权下签发令牌,也不会把签发当作另一项任务的顺手步骤。

参数：

• name — 令牌标签,最多 30 个字符;仅用于识别,不参与鉴权
• expires_at — 可选,过期时间,ISO 8601 UTC 格式(如 2026-11-15T00:00:00Z),必须是未来时刻。省略时默认自创建起 90 天。

user_revoke_personal_access_tokenCopy Anchor Link

吊销一个个人访问令牌。吊销后,工具会重新读取列表以确认令牌已失效。

参数：

• id — 令牌 ID,来自 user_list_personal_access_tokens,不是令牌明文
• confirm_name — 必须与令牌的当前名称完全一致

Compute(算力容器)Copy Anchor Link

用于操作算力容器与项目的工具——与控制台中算力容器部分是同一批对象。操作特定容器或项目的工具都接受可选的 username 参数：传入组织 ID 即可操作该组织的资源,且同一容器的每次后续调用都要传相同的值。

compute_list_jobsCopy Anchor Link

列出你的工作空间与任务容器,按创建时间从新到旧排序。每条记录是项目的一次运行。

参数：

• username — 可选,你所属的组织(所属组织可通过 user_get_profile 查看);省略则列出个人账号下的容器
• status — running / succeeded / failed / cancelled / all(默认 all)
• q — 按容器名称子串匹配
• page — 页码

compute_list_projectsCopy Anchor Link

列出项目,可按标签筛选。

参数：

• username — 可选,你所属的组织(所属组织可通过 user_get_profile 查看)
• q — 按项目名称子串匹配
• tags — 可选,只列出同时带有这些标签的项目(平台标签目录中的精确名称,区分大小写)
• page — 页码

compute_list_resourcesCopy Anchor Link

列出可用的算力资源型号(GPU/CPU),含规格、余额是否足以使用、当前负载情况。

参数：

• username — 可选

compute_list_plansCopy Anchor Link

列出计费方案：按量付费与包时套餐(含时长与价格)。

参数：

• resource — 可选,来自 compute_list_resources 的资源名称

compute_list_runtimesCopy Anchor Link

列出可用的容器运行时环境(镜像),不含已弃用的版本。

参数：

• username — 可选

compute_get_jobCopy Anchor Link

获取容器的完整详情,包括访问地址。密钥值会被脱敏。

参数：

• job_id_or_url — 容器 ID 或控制台容器页面 URL
• username — 可选,拥有该容器的组织;省略则查询个人账号下的容器

compute_get_job_metricsCopy Anchor Link

获取容器的系统指标与自定义指标摘要(最新值 / 最小 / 最大 / 平均)。

参数：

• job_id — 容器 ID

compute_get_projectCopy Anchor Link

获取项目详情及其容器执行历史(工作空间与任务的运行记录)。

参数：

• project_id_or_url — 项目 ID 或控制台 URL
• status — 筛选执行历史：running / succeeded / failed / cancelled / all
• page — 页码
• username — 可选,拥有该项目的组织;省略则查询个人账号下的项目

compute_get_job_readmeCopy Anchor Link

读取容器的 README,返回已渲染的 HTML。容器没有 README 是正常结果——教程内容通常在 Notebook 里。

参数：

• job_id_or_url — 容器 ID、项目 ID 或控制台 URL

compute_get_job_notebookCopy Anchor Link

读取容器的 Notebook 内容。Notebook 内容只有在容器停止后才能读到：运行中的容器(典型情况是刚克隆的教程)即使 Notebook 已经在磁盘上也会返回空。助手会把这种情况当作"暂时读不到",而不是"容器是空的",并改为给你容器的 Jupyter 链接。

参数：

• job_id_or_url — 容器 ID、项目 ID 或控制台 URL

compute_get_create_job_guideCopy Anchor Link

返回创建容器的推荐流程说明(计费、数据绑定、环境变量、端口、在组织下创建、克隆公开教程)。助手应在调用 compute_create_job 前先阅读。

有一条规则值得了解：新注册、账号里还没有任何项目、容器和数据集时,你说"想试试跑个 notebook",助手会先推荐克隆一个热门的公开教程(通过 resources_search_public_projects),而不是直接创建空白容器。

无参数。

compute_create_jobCopy Anchor Link

创建新的工作空间容器。容器一启动即开始计费,因此助手会先复述计划(资源、镜像、项目、计费)并等待你的明确同意后再调用——即使资源是你自己点名的。

参数：

• resource — 必填,来自 compute_list_resources 的资源名称
• runtime — 必填,来自 compute_list_runtimes 的运行时名称
• project_id / new_project_name — 二选一：在已有项目中创建,或新建项目
• description — 可选,容器描述
• plan_id — 可选,来自 compute_list_plans 的包时套餐;省略则按量付费
• auto_renew — 包时套餐是否自动续费(默认 true)
• idle_timeout_minutes — 闲置自动停止时间(默认 30,0 表示禁用)
• env — 环境变量,{name, value, secret} 列表;value 可以是文本、数字或布尔值
• data_bindings — 要挂载的数据,{source, mount_path, writable} 列表
• ports — 自定义端口映射,{port, name} 列表
• username — 可选,组织 ID(而非显示名称),在该组织名下创建容器。容器费用记入组织余额,且该容器的每次后续调用都必须传相同的 username;省略则在个人账号下创建

该工具遵循与控制台一致的规则：

• 数据绑定挂载在 /input0 到 /input4(只读来源,如数据集和模型)与 /output(只能绑定形如 <owner>/jobs/<job-id>/output 的历史容器输出)。参见数据绑定。
• 环境变量不能使用保留前缀 OPENBAYES_,名称中含 TOKEN / SECRET / KEY / PASSWORD 的必须标记为密钥。参见环境变量。
• 环境变量的值按你写的原样发送。数字({ "name": "NCCL_SHM_DISABLE", "value": 1 })和字符串("value": "1")到容器里都是常规文本(NCCL_SHM_DISABLE=1),区别只在 openbayes_params.json 里记录的类型以及读回容器时返回的类型,按你的代码期望的类型来选即可。不接受嵌套值(对象与数组)。密钥值原样发送,不做转换。
• 8080 端口为容器内置服务保留,不能映射。参见自定义端口映射。
• 所选资源必须在当前余额下可用且未满载,所选计费方案必须属于该资源。

compute_create_projectCopy Anchor Link

创建一个空项目——只有项目本身,不启动任何容器,不产生费用。用于提前建好项目(名称、描述、标签);compute_create_job 的 new_project_name 也会隐式建项目,但不能打标签,且总会启动一个计费容器。每次调用都会新建项目,所以助手会先查 compute_list_projects,绝不按名字复用已有项目。写入前工具会检查账号的项目数量上限,并把每个标签与平台标签目录校验。创建项目属于确认档操作：助手会复述名称、所有者与标签并等待你同意。

参数：

• name — 必填,项目名称
• description — 可选,描述
• tags — 可选,标签列表;平台标签目录中的现有名称,区分大小写
• username — 可选,组织 ID,在该组织名下创建项目

compute_stop_jobCopy Anchor Link

停止正在运行的容器。

参数：

• job_id — 必须是准确的容器 ID,不接受 URL
• username — 可选,拥有该容器的组织;省略则操作个人账号下的容器

compute_restart_workspaceCopy Anchor Link

以先前的配置重启已停止的工作空间容器。重启会按先前资源的费率恢复计费,因此助手会先复述容器、其资源与计费后果并等待你的明确同意——即使重启是你自己要求的。

参数：

• job_id — 容器 ID
• username — 可选,拥有该工作空间的组织——重启费用记入组织余额;省略则操作个人账号下的容器

compute_update_jobCopy Anchor Link

修改容器的描述——给某一次运行记一笔,比如它是干什么的、产出了什么。运行中和已停止的容器都可以改;容器的其他设置不变。零成本、可逆,无需确认。成功判据是描述按写入值读回。

参数：

• job_id — 必须是准确的容器 ID,不接受 URL
• description — 新描述(空字符串表示清空)
• username — 可选,拥有该容器的组织;省略则操作个人账号下的容器

compute_update_projectCopy Anchor Link

更新项目设置：名称、描述、闲置超时与标签。项目的可见范围由单独的工具 compute_update_project_permissions 负责。

参数：

• project_id_or_url — 项目 ID 或控制台 URL
• name — 可选,新名称
• description — 可选,新描述
• idle_timeout_minutes — 可选,作用于整个项目,0 表示禁用
• add_tags / remove_tags — 可选,标签列表;标签会与平台标签目录校验
• username — 可选,拥有该项目的组织;省略则操作个人账号下的项目

compute_update_project_permissionsCopy Anchor Link

修改谁能看到一个项目(及其容器的 Notebook 与输出)。visibility 可选 private(仅所有者)、public(平台上任何人可浏览与查看)或 public_download(任何人还可批量下载——仅在你明确要求时使用,且组织名下的项目不支持)。org_access 仅对组织名下的项目有效:private(成员不可见)、read_download 或 write。只传要改的字段;所有者会从项目自身解析。

工具会在写入前套用平台自身的规则并解释拒绝原因:org_access 只对组织项目有效;组织项目不接受 public_download;组织项目不能在对公众公开的同时对成员设为 private——工具会点名该补哪个参数,而不会自行抬高另一档。写入后还会核对平台返回的档位与请求一致。把项目设为公开并不会让它出现在公共列表页——列表由标签驱动,需要管理员流程。

修改可见范围属于确认档操作：助手会复述当前与目标档位(组织项目会列出两个字段)并等待你同意,即使档位是你自己点名的。

参数：

• project_id_or_url — 项目 ID 或控制台 URL
• visibility — 可选,private / public / public_download
• org_access — 可选,仅组织名下的项目;private / read_download / write

compute_update_job_portsCopy Anchor Link

为容器添加或移除自定义端口映射。映射后的端口会获得一个公网可访问的 URL,也就是说开放端口会把监听该端口的服务发布到互联网——助手应在开放端口前与你确认。8080 端口为保留端口,不能映射。

参数：

• job_id — 容器 ID
• add_ports — {port, name} 列表
• remove_ports — 要移除的端口号列表
• username — 可选,拥有该容器的组织;省略则操作个人账号下的容器

compute_delete_jobCopy Anchor Link

永久删除项目中的一次运行(容器)及其 /output 数据。占用的存储立即释放;挂载了这次运行输出的其他容器或模型服务会丢失该数据;项目及其他运行保留。运行必须已经结束(CANCELLED、SUCCEEDED 或 FAILED)——运行中的要先停止。删除后工具会重新读取该运行以确认删除成功。

参数：

• job_id — 必须是准确的容器 ID,不接受 URL
• confirm_name — 必须与运行名称完全一致,即 compute_list_jobs 显示的形式,如 my-project/3
• username — 可选,拥有该容器的组织;省略则操作个人账号下的容器

compute_delete_projectCopy Anchor Link

永久删除项目及其中全部运行记录和它们的 /output 数据——挂载了这些输出的对象会丢失数据。不能有运行中的容器：先用 compute_stop_job 停止并等到 CANCELLED。删除后工具会重新读取该项目以确认删除成功。

参数：

• project_id_or_url — 项目 ID 或控制台 URL
• confirm_name — 必须与项目当前的名称完全一致;工具与平台各校验一次

Resources(公共资源)Copy Anchor Link

用于发现平台公共内容的工具。

resources_search_public_projectsCopy Anchor Link

搜索公共项目(教程与社区项目),支持按标签筛选。每条结果都带有克隆次数,可作为热度参考;公共项目可以克隆为新容器的起点。

参数：

• q — 搜索关键词
• tags — 用于筛选的标签名称列表
• sort — 结果排序：LAST_ACTIVE_AT_DESC(默认)/ LAST_ACTIVE_AT_ASC / CLONE_COUNT_DESC / CLONE_COUNT_ASC;找最热门的项目用 CLONE_COUNT_DESC
• page — 页码

Dataset(数据集与模型)Copy Anchor Link

用于管理数据集与模型的工具——搜索、查看详情、创建条目与版本、更新元数据、修改可见范围与删除。不包括数据上传：上传需在网页控制台完成。

dataset_searchCopy Anchor Link

一次调用同时搜索自有与公共的数据集和模型。每条结果包含可作为 compute_create_job 中 data_bindings 来源的绑定名称。

参数：

• q — 搜索关键词
• category — dataset / model / all(默认 all)
• username — 可选,在所属组织下搜索而非个人账号
• tags — 用于筛选公共结果的标签名称列表;标签是平台受控词表,需精确匹配
• page — 自有结果的页码
• public_page — 公共结果的页码

dataset_getCopy Anchor Link

一次调用获取数据集或模型的完整详情：元数据、所有者、权限、全部版本,以及所选版本的 README(已渲染的 HTML)。每个版本都带有可作为 compute_create_job 中 data_bindings 来源的绑定名称;顶层容量为全部版本之和。

参数：

• dataset_id_or_url — 数据集/模型 ID 或控制台 URL;URL 末尾的版本号会被识别
• version — 可选,版本号;优先于 URL 中的版本

dataset_createCopy Anchor Link

创建一个新的空数据集或模型条目——仅包含元数据,没有版本和数据。每次调用都会新建一个条目,请先用 dataset_search 检查是否已存在,避免重复创建。助手会先复述条目内容(名称、类别、所有者、标签)并等待你的明确同意后再调用。

参数：

• name — 必填,条目名称
• kind — dataset / model(默认 dataset)
• description — 可选,描述
• tags — 可选,标签列表;标签必须是平台标签目录中的现有名称(区分大小写)
• username — 可选,在所属组织下创建而非个人账号

dataset_updateCopy Anchor Link

更新数据集或模型的元数据：名称、描述、类别与标签。只传需要修改的字段。组织名下的条目可直接操作——所有者会被自动解析。条目的可见范围由单独的工具 dataset_update_permissions 负责。

参数：

• dataset_id_or_url — 数据集/模型 ID 或控制台 URL
• name — 可选,新名称
• description — 可选,新描述
• kind — 可选,在 dataset 与 model 之间切换
• add_tags / remove_tags — 可选,标签列表;标签会在写入前与平台标签目录校验

dataset_update_permissionsCopy Anchor Link

修改谁能看到一个数据集或模型。visibility 可选 private(仅所有者)、public(平台上任何人可浏览与查看)或 public_download(任何人还可批量下载——仅在你明确要求时使用,且组织名下的条目不支持)。org_access 仅对组织名下的条目有效:private(成员不可见)、read_download 或 write。只传要改的字段。

工具会在写入前套用平台自身的规则并解释拒绝原因:org_access 只对组织条目有效;组织条目不接受 public_download;组织条目不能在对公众公开的同时对成员设为 private——工具会点名该补哪个参数,而不会自行抬高另一档。写入后还会核对平台返回的档位与请求一致。把条目设为公开并不会让它出现在公共列表页——列表由标签驱动,需要管理员流程。

修改可见范围属于确认档操作：助手会复述当前与目标档位(组织条目会列出两个字段)并等待你同意,即使档位是你自己点名的。

参数：

• dataset_id_or_url — 数据集/模型 ID 或控制台 URL
• visibility — 可选,private / public / public_download
• org_access — 可选,仅组织名下的条目;private / read_download / write

dataset_create_versionCopy Anchor Link

为已有的数据集或模型添加一个新的空版本——下一个版本号,暂时没有数据。数据之后通过控制台上传;空版本在有内容之前不能挂载到容器。最新版本本身还是空的时候工具会拒绝(先填那一个),成功时返回新版本的绑定名称。创建版本属于确认档操作：助手会复述条目及其当前最新版本并等待你同意。

参数：

• dataset_id_or_url — 数据集/模型 ID 或控制台 URL

dataset_deleteCopy Anchor Link

永久删除数据集或模型,包括所有版本和已上传的全部数据。删除后工具会重新读取该条目以确认删除成功。

参数：

• dataset_id_or_url — 数据集/模型 ID 或控制台 URL
• confirm_name — 必须与条目当前的名称完全一致

Org(组织)Copy Anchor Link

用于查询所属组织的工具。三个工具均为只读——邀请成员、变更角色与退出组织都需在控制台操作。组织的 ID 可作为 compute 与 dataset 工具的 username 参数使用——既可列出组织资源(compute_list_jobs、dataset_search),也可在组织名下创建与管理资源(compute_create_job、dataset_create)。

org_listCopy Anchor Link

列出你所属的组织,含你在每个组织中的角色(OWNER / MEMBER / PENDING)与该组织下的能力标志(如 canCreateProject、canCreateInvitation)。"在这个组织里能不能做某事"以能力标志为准,而非角色。

无参数。

org_getCopy Anchor Link

获取单个组织的详情：资料(显示名、描述、类型、锁定状态)、席位配额(已用 / 总数 / 剩余)、你在该组织中的能力标志,以及该组织的资源限制——每种资源与 GPU 类型同时能开几个容器、数据集与项目的数量上限、上传大小限制。用 username 在组织名下创建的资源受这些限制约束,而不是受你个人的限制(user_get_quota)约束。

参数：

• org_id — 组织 ID,而非显示名

org_list_membersCopy Anchor Link

列出组织成员,每页 30 条：用户名、显示名、角色与加入时间,并标明你是否可以移除某个成员或变更其角色。角色为 PENDING 的行是尚未接受的邀请。

参数：

• org_id — 组织 ID
• page — 页码

Serving(模型部署)Copy Anchor Link

用于把模型部署为推理服务并管理它们的工具——与控制台中模型部署部分是同一批对象。一个 serving 是一个稳定的服务端点;它背后的每次部署是一个不可变的版本(运行时、资源、副本数与数据绑定在版本创建时冻结)。同一个 serving 同时只运行一个版本：启动或重启某个版本会停掉正在运行的那个。操作特定 serving 的工具都接受可选的 username 参数：传入组织 ID 即可操作该组织的 serving,且同一 serving 的每次后续调用都要传相同的值。

账号需要开通模型部署功能;未开通时,serving_list 与 serving_create 会直接说明,而不是返回空列表或权限错误。

serving_listCopy Anchor Link

列出你的模型服务,按创建时间从新到旧排序,含每个服务的活跃版本(状态、副本数、资源)与最新版本。链接名称:frontend 是控制台页面,http 是服务端点,llm 表示该端点兼容 OpenAI 接口(与 http 是同一个 URL,不是第二个地址)。

参数：

• username — 可选,你所属的组织;省略则列出个人账号下的服务
• status — running / stopped / failed / all(默认 all);running 也包含正在启动或正在关闭的服务
• q — 按服务名称子串匹配
• page — 页码

serving_getCopy Anchor Link

获取单个服务的详情及其一个版本：状态与子状态、副本数、资源、运行时、实例及其就绪情况、数据绑定、端点链接,以及控制面就绪判定。默认显示当前正在运行的版本——回滚之后它可能比最新版本更旧;没有版本在运行时显示最新版本。响应会注明选的是哪一种,并带上最新版本号。

这里的就绪只是控制面就绪:RUNNING 本身不能证明服务能正常响应,助手会请求 http 链接来确认数据面。needAuthorization 为 true 表示调用方必须携带 API Key。子状态 QUOTA_EXHAUSTED 表示平台因余额耗尽停掉了该版本。

参数：

• serving_id_or_url — 服务 ID 或控制台服务页面 URL
• version — 可选,指定要显示的版本号
• username — 可选,拥有该服务的组织;省略则查询个人账号下的服务

serving_get_metricsCopy Anchor Link

获取版本的资源利用率——CPU(用户态 / 系统态)、内存、每张 GPU 的利用率与显存——按实例汇总为最新值 / 平均 / 最大。默认是默认版本最近 30 分钟、60 秒一个桶。数值按平台上报的原样返回(内存与显存为字节,CPU 为毫核)。

参数：

• serving_id_or_url — 服务 ID 或控制台 URL
• version — 可选,版本号;省略则为最新版本
• from / to — 时间窗：相对偏移(-30m、-24h、-3d)、毫秒时间戳或 now(默认 -30m 与 now)
• resolution — 桶大小,如 60s、16m、1h、1d(默认 60s)
• username — 可选,拥有该服务的组织

serving_get_telemetryCopy Anchor Link

获取版本的请求遥测,每次调用读一种信号:requests(每个桶内的请求数与耗时分布)、latency / ttft / total_tokens(LLM 请求延迟、首 token 时间、每请求 token 数——适用于链接中带 llm 的服务)、events(逐请求事件行)与 llm_events(逐 LLM 请求的 token 与延迟行)。分布类信号返回按请求数加权的汇总,以及原始的桶数据。

对 LLM 服务而言 llm 系列是主要信号——通用的 requests 与 events 流可能为空而 LLM 流正常,所以通用遥测为空不能证明没有流量。

参数：

• serving_id_or_url — 服务 ID 或控制台 URL
• signal — 必填,requests / latency / ttft / total_tokens / events / llm_events
• version — 可选,版本号;省略则为最新版本
• from / to — 时间窗,格式同 serving_get_metrics(默认 -30m 与 now)
• resolution — 分布类信号的桶大小(默认 60s);事件类信号忽略
• tail — events / llm_events 返回最近多少行(默认 100)
• method — requests 按 HTTP 方法筛选(默认 POST)
• username — 可选,拥有该服务的组织

serving_get_deploy_guideCopy Anchor Link

返回把模型部署为服务的分步指南：工作目录必须包含什么(带 OPENBAYES_SERVING_PRODUCTION 端口切换的 start.sh)、推荐先在工作空间里测通的流程、serving_create 如何从来源容器推导版本配置、验证方法、API Key,以及先停止再删除的顺序。当你要求部署模型、把容器做成 API 端点、发布新版本,或者不确定该重启还是发新版本时,助手会先阅读它。

无参数。

serving_createCopy Anchor Link

创建服务并部署第一个版本。版本一启动即开始计费(资源 × 副本数),因此助手会先复述计划——资源、运行时、绑定、副本数以及计费开始——并等待你的明确同意,即使容器或资源是你自己点名的。

描述版本有两种方式:

• 从测通的工作空间容器部署——传 source_job_id。工具把资源锁定为该容器的资源,在目录中匹配它的运行时,保留容器的输入绑定(只读),并把容器自己的输出挂到 /output。此时 data_bindings 只能追加 /input* 挂载;出现 /output 会被拒绝。
• 显式指定——自己传 resource、runtime 与 data_bindings,其中必须恰好有一个绑定在 /output。

无论哪种方式,挂在 /output 的内容都必须包含 start.sh,脚本要根据环境变量 OPENBAYES_SERVING_PRODUCTION 切换端口(工作空间里 8080,服务里 80)并监听 0.0.0.0。工具无法查看容器或数据集内部,所以助手会在调用前与你确认这一点。脚本写法参见模型部署快速上手。

参数：

• name — 必填,服务名称
• description — 可选,描述
• source_job_id — 可选,作为来源的容器
• resource — 来自 compute_list_resources 的资源名称;传 source_job_id 时省略(自动继承)
• runtime — 来自 compute_list_runtimes 的运行时名称;传 source_job_id 时省略则继承,传入则迁移
• data_bindings — 只读挂载,{data, mount_path} 列表;data 是 dataset_search 返回的数据集绑定名称或容器输出 <owner>/jobs/<job-id>/output,mount_path 是 /input0 … /input4 或 /output
• replica — 实例数(默认 1);费用按副本数倍增
• username — 可选,组织 ID,在该组织名下创建服务并记入组织余额;每次后续调用都必须传相同的值

写入前工具会检查：模型部署功能已开通,资源存在、余额可负担且未满载,该资源的并发上限还有空位(服务与容器占用同一名额——名额已满时先停掉来源工作空间),以及运行时可用。

serving_create_versionCopy Anchor Link

为已有服务部署新版本——用于工作空间有改动(/output 里的代码或模型更新了)、想换运行时或资源,或想换一套绑定。版本一启动即开始计费,且该服务正在运行的版本会被停掉。配置来自 source_job_id 或显式的 resource + runtime + data_bindings,规则与检查同 serving_create。助手会先复述计划(包括正在运行的版本会被停掉)并等待你的明确同意。

配置不变、只想把停掉的版本拉起来,不要用这个工具——那是 serving_restart_version。为配置完全相同的重启新建版本会浪费一个版本号,并让固定在旧版本上的调用方失效。

参数：

• serving_id_or_url — 服务 ID 或控制台 URL
• source_job_id / resource / runtime / data_bindings — 同 serving_create
• replica — 实例数;默认沿用最新版本的副本数
• description — 可选,版本备注,例如改了什么
• username — 可选,拥有该服务的组织

serving_restart_versionCopy Anchor Link

把已停止(CANCELLED)或失败(FAILED)的版本以冻结配置重新拉起——同样的运行时、资源、绑定与副本数,不产生新版本号。"重启 serving"、"被停了帮我起回来"、"把 cancelled 的版本重新启动"指的就是它。重启会恢复计费,且如果该服务有别的版本在运行,那个版本会被停掉,因此助手会先复述服务、版本、资源、副本数与后果并等待你的明确同意。

只有 CANCELLED 或 FAILED 的版本可以重启:RUNNING 的不需要重启,PREPARING 的已经在启动,CANCELLING 的要先等它变成 CANCELLED——工具会说明具体是哪种情况。

参数：

• serving_id_or_url — 服务 ID 或控制台 URL
• version — 可选,版本号;省略则为最新版本
• username — 可选,拥有该服务的组织——重启费用记入组织余额

serving_update_versionCopy Anchor Link

修改版本上唯一可变的两项设置:replica(为运行中的版本扩缩容——费用随之变化)与 description(版本备注)。运行时、资源与绑定按版本冻结——要改它们请用 serving_create_version。对已停止的版本修改 replica 会被拒绝并指向 serving_restart_version。修改 replica 属于确认档操作;只改备注无需确认。

参数：

• serving_id_or_url — 服务 ID 或控制台 URL
• version — 可选,版本号;省略则为最新版本
• replica — 运行中版本的新实例数
• description — 新的版本备注
• username — 可选,拥有该服务的组织

serving_updateCopy Anchor Link

修改服务自身的设置:name、description 与 need_authorization(访问控制开关)。开启后,所有不带有效 API Key 的调用都会失败(用 serving_create_api_key 签发);关闭后端点可公开调用。变更最长需要 5 分钟生效。修改 need_authorization 属于确认档操作;只改名称或描述无需确认。参见 API Key 管理。

参数：

• serving_id_or_url — 服务 ID 或控制台 URL
• name — 可选,新名称
• description — 可选,新描述
• need_authorization — 可选;true 要求携带 API Key,false 使端点公开
• username — 可选,拥有该服务的组织

serving_stop_versionCopy Anchor Link

停止运行中的版本。该版本的端点随即下线,调用方立即失败;该版本的计费停止。版本保留其配置,可用 serving_restart_version 重新拉起(冷启动,内存中的状态会丢失)。不传 version 时,工具停止的是实际在运行的那个版本。

参数：

• serving_id_or_url — 服务 ID 或控制台 URL
• version — 可选,版本号;省略则为正在运行的版本
• username — 可选,拥有该服务的组织

serving_delete_versionCopy Anchor Link

永久删除服务的一个版本。只有 CANCELLED 或 FAILED 的版本可以删除——运行中的要先停止。删除后工具会重新读取该版本以确认删除成功。

参数：

• serving_id_or_url — 服务 ID 或控制台 URL
• version — 必填,要删除的版本号
• username — 可选,拥有该服务的组织

serving_deleteCopy Anchor Link

永久删除服务——包括端点、配置与全部版本。不能有版本在运行：先停止它们并等到 CANCELLED。删除后工具会重新读取该服务以确认删除成功。

参数：

• serving_id_or_url — 服务 ID 或控制台 URL
• confirm_name — 必须与服务当前的名称完全一致;工具与平台各校验一次
• username — 可选,拥有该服务的组织

serving_list_api_keysCopy Anchor Link

列出用于调用模型服务的 API Key：记录 ID、名称、范围、绑定的服务、创建与最近使用时间。密钥本身在创建之后永远不可再获取——列表里没有 Key 的值,丢了就只能签发新的并吊销旧的。记录 ID 是 serving_update_api_key 与 serving_revoke_api_key 需要的参数。

范围是根据绑定的服务推断的,因为平台不报告 Key 的类型：有绑定服务的 Key 是 serving 范围;没有绑定的显示为 account——而 serving 范围的 Key 在其绑定的服务被删除后看起来也是这样。

参数：

• page — 页码
• username — 可选,要列出哪个组织的 Key

serving_create_api_keyCopy Anchor Link

为开启了访问控制的服务签发 API Key。范围 serving 把 Key 绑定到指定的服务;范围 account 可访问账号下的全部服务。新 Key 最长需要 5 分钟生效。助手会先复述 Key 的名称与范围并等待你的明确同意。

参数：

• name — 必填,Key 名称
• scope — 必填,serving 或 account
• serving_ids — Key 可访问的服务;范围为 serving 时必填
• username — 可选,组织 ID,为该组织的服务签发 Key

serving_update_api_keyCopy Anchor Link

重命名 Key 或修改其范围——可访问哪些服务,或是否可访问账号下的全部服务。密钥本身不变。收窄范围会让被移除服务上的调用方在最长 5 分钟内断开。修改范围属于确认档操作;只改名无需确认。

有绑定服务的 Key 可以省略 scope 直接改名。没有绑定的 Key——账号级的,或 serving 级但绑定的服务已被删除的——必须显式传 scope：工具绝不会自行假定为 account,否则会静默放开全部服务的访问。

参数：

• id — Key 的记录 ID,来自 serving_list_api_keys,不是密钥本身
• name — 可选,新名称
• scope — 可选,serving 或 account
• serving_ids — 范围为 serving 时的完整新服务集合
• username — 可选,拥有该 Key 的组织

serving_revoke_api_keyCopy Anchor Link

吊销一个服务 API Key。所有仍在使用它的调用方会在最长 5 分钟内断开。吊销后工具会重新读取列表以确认 Key 已消失。

参数：

• id — Key 的记录 ID,来自 serving_list_api_keys,不是密钥本身
• confirm_name — 必须与 Key 的当前名称完全一致
• username — 可选,拥有该 Key 的组织