模型部署介绍

完成模型训练后，可以将模型部署到服务端提供实时的模型推理服务。「模型部署（Serving）」是 HyperAI 提供的服务端模型推理功能。

部署模式Copy Anchor Link

HyperAI 模型部署支持两种部署模式：

1. 自定义部署（推荐）：通过编写 start.sh 启动脚本，完全自定义服务的启动方式。
2. 传统的 predictor.py 方式：使用 HyperAI 提供的预定义框架。

API Key 认证Copy Anchor Link

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

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

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

自定义部署方式（推荐）Copy Anchor Link

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

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

自定义部署要求Copy Anchor Link

1. 必需文件：

   • start.sh - 启动脚本，需要确保：
     • 监听 80 端口
     • 处理 HTTP 请求
   • 模型文件及其他依赖文件

2. 可选文件：

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

示例Copy Anchor Link

你可以使用任何框架（如 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

数据绑定Copy Anchor Link

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

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

数据绑定特点Copy Anchor Link

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

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

选择绑定目录Copy Anchor Link

绑定时的选取方式与算力容器类似，具体操作请参考 算力容器数据绑定。

版本管理Copy Anchor Link

模型部署支持版本管理：

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

详细的操作介绍请参考 模型部署的管理。

启动与就绪Copy Anchor Link

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

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

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

传统部署方式（predictor.py）Copy Anchor Link

如果你希望使用 HyperAI 提供的预定义框架，可以选择这种方式。

1. 必需文件：

   • predictor.py - 包含 Predictor 类的模型部署脚本
   • 模型文件

2. 可选文件：

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

详细的编写规则请参考 Serving 服务编写，编写样例请参考 openbayes-serving-examples 仓库。