跳到主要内容

模型部署介绍

在完成了模型的训练后可以将模型以某种方式部署到服务端或者存放到设备端对外提供实时的模型推理服务。「模型部署（Serving）」就是 OpenBayes 提供的服务端模型推理功能。

部署模式​

OpenBayes 模型部署采用 start.sh 自定义启动脚本的方式，你可以完全控制服务启动流程。

配额限制​

模型部署同样受账号级 limitation 影响，包括：

  • 私有 / 公有模型部署个数限制；
  • 所使用资源的并行限制；
  • GPU 类型总量限制。

如果你在创建模型部署、切换公开状态或启动版本时遇到限制，请参考 配额限制。

API Key 认证​

OpenBayes 模型部署支持使用 API Key 进行安全认证。相比 JWT Token 认证方式，API Key：

  • 提供更细粒度的访问控制
  • 支持独立的密钥管理和追踪
  • 符合业界标准实践（如 OpenAI、HuggingFace 等）

你可以在模型部署的设置页面中创建和管理 API Key。详细信息请参考 API Key 管理。

自定义部署方式（推荐）​

这是最简单和灵活的部署方式。你只需要：

  1. 准备好模型文件
  2. 编写一个 start.sh 脚本来启动你的服务

自定义部署要求​

  1. 必需文件：

    • start.sh - 启动脚本，需要确保：
      • 监听 0.0.0.0:80（必须绑定 0.0.0.0，不要绑 127.0.0.1 或 localhost，否则平台无法探测到你的服务）
      • 处理 HTTP 请求
    • 模型文件及其他依赖文件

  2. 可选文件：

    • requirements.txt - 用于安装 Python 依赖
    • conda-packages.txt - 用于安装 Conda 依赖
    • dependencies.sh - 用于安装系统依赖
    • .env - 用于设置环境变量

示例​

你可以使用任何框架（如 FastAPI、Flask、Gradio 等）来提供服务。这里是一个使用 FastAPI 的简单示例：

# app.py
from fastapi import FastAPI
import uvicorn

app = FastAPI()

@app.get("/")
def predict():
    return {"message": "Hello World"}
# start.sh
#!/bin/bash
pip install fastapi uvicorn
uvicorn app:app --host 0.0.0.0 --port 80

数据绑定​

在创建模型部署时，你可以绑定一个或多个数据目录。数据绑定的方式与模型训练的数据绑定基本相同，可以选择以下来源：

  • 公开数据集或模型
  • 个人私有的数据集或模型
  • 算力容器的工作目录
  • 通过文件上传的数据仓库

数据绑定格式与 Job 基本一致，常见写法如下：

  • 数据集版本：<owner>/<dataset-ref>/<version>
  • Job 输出：<owner>/jobs/<job-ref>/output

手工编写 CLI、YAML 或 API 参数时，推荐优先使用数据集 ID 或 Job ID 作为 ref，避免名称中的空格、转义或歧义问题。更完整的格式说明见数据绑定。

数据绑定特点​

模型部署的数据绑定与模型训练有以下区别：

  1. 只读绑定：所有数据绑定都是只读模式，无法进行写入或修改操作
  2. 多目录绑定：可以同时绑定多个数据目录到不同的挂载点：
    • /openbayes/input/input0
    • /openbayes/input/input1
    • /openbayes/input/input2
    • /openbayes/input/input3
    • /openbayes/input/input4
  3. 工作目录特性：
    • 工作目录（/openbayes/home）中的内容是在部署启动时从绑定源拷贝而来
    • 重要提示：由于工作目录的内容在重启后会丢失，建议将所有必要的模型文件和依赖放在绑定的数据目录中

Serving 的额外限制​

与 Job 相比，Serving 的数据绑定还有以下约束：

  1. 仅支持两类绑定源：只支持数据集版本和 Job 输出，不支持其他特殊绑定方式
  2. 必须存在 /output 绑定：创建 ServingVersion 时，至少需要有一个绑定挂载到 /output
  3. /output 必须包含启动文件：挂载到 /output 的绑定源中必须存在 start.sh
  4. 挂载路径不能重复：同一个 ServingVersion 中，/output、/input0 ~ /input4 不能重复使用

其中 /output 对应容器内的工作目录 /openbayes/home，通常用于放置部署启动所需的代码、模型文件和依赖描述文件。

选择绑定目录​

绑定时的选取方式与算力容器类似：

serving 数据绑定

版本管理​

模型部署支持版本管理：

  • 版本之间相互独立，可以支持不同的运行时环境、资源类型以及部署内容
  • 当部署新版本时，老版本会自动下线
  • 版本号以数字序号递增

详细的操作在 模型部署的管理 有介绍。

启动脚本约定​

start.sh 中通常包含以下步骤：

  1. 准备运行环境（例如安装依赖、激活 Conda 环境）
  2. 加载模型与配置
  3. 启动 HTTP 服务并监听 0.0.0.0:80

更多细节请参考 快速上手 与 依赖管理。

启动与就绪​

部署启动后，平台不会立刻把流量打进来，而是等待你的服务在容器内监听 0.0.0.0:80，端口可连接后才将该版本标记为就绪并开始接收请求。

加载大模型（下载权重、载入显存）通常需要数分钟，这段时间 Pod 处于“未就绪”是正常现象，不代表部署失败。为了让你能看到进度，平台会在部署日志中输出启动阶段的提示：

===== 等待服务监听 80 端口，监听成功后才会接收请求 =====
===== 服务尚未监听 80 端口，已等待 N 分钟，请确认服务监听地址为 0.0.0.0:80 =====
===== 已检测到 80 端口，服务就绪 =====

若服务监听在错误的端口（而非 80），日志会改为如下提示，并随后重启、多次失败后停止本次部署（不会出现上面的“服务就绪”）：

===== 检测到服务正在监听 8000 端口，而平台要求监听 0.0.0.0:80，平台即将重启服务；多次失败后会自动停止本次部署 =====
  • 看到“服务就绪”即表示端口已就绪、版本开始接收请求。
  • 如果反复看到“服务尚未监听 80 端口，已等待 N 分钟”，按以下顺序排查：
    • 绑定地址：检查 start.sh 传给框架的 host 参数，推荐绑 0.0.0.0。平台从容器内（loopback）探测端口——绑到某个具体 pod IP 会探测不到、判定失败；绑 127.0.0.1 / localhost 虽能被探测就绪，但仍建议用 0.0.0.0 以覆盖所有访问路径；
    • 监听端口：确认框架实际监听的是 80 端口；
    • 启动失败或仍在加载：查看部署日志中框架自身（vLLM、FastAPI 等）的输出，确认是否有报错或仍在下载 / 载入模型。
  • 平台会尽快判定明确的启动失败，不必等满超时：
    • 启动即崩溃：进程启动后很快退出（脚本跑完就结束、或崩溃），平台会在几分钟内判定失败并回收资源（释放 GPU），并在日志中提示。修法：确保服务前台常驻运行，start.sh 末尾不要直接退出。
    • 监听了错误的端口或地址：进程一直活着，但没有监听容器内的 0.0.0.0:80（例如误监听 8000，或绑到了某个具体的 pod IP 而非 0.0.0.0）。平台检测到后会在日志中告诉你服务实际监听的端口，并在几分钟内判定失败回收。修法：让服务监听 0.0.0.0:80。
    • 仍在加载（真的慢）：进程活着、什么端口都还没监听（例如大模型正在下载/载入显存），平台会给较长的启动允许期（最长约 1 小时）等它就绪；超过仍未监听 80 端口才判定失败。请确保耗时操作能在该时间内完成，必要时把模型预置到绑定的数据集里以避免每次冷启动重新下载。
提示

部署日志只反映平台侧的端口探测状态。你的服务自身（如 vLLM、FastAPI）的加载与报错日志同样会输出到部署日志中，排查启动问题时以这些框架日志为准。

最后由 xushanchuan 于 更新