文档导航

Docker 快速开始

不必在主机上安装 Python 或 PyTorch 就能运行 SDK。CPU 快速开始请预留 8 GB 内存和 10 GB 空闲 磁盘,并装好 Docker Engine 或 Docker Desktop 以及 Compose v2 或更新版本。

在仓库根目录执行:

docker compose run --build --rm laya

这会构建当前 checkout,在 CPU 上运行示例请求 并打印覆盖 choice、score 和 noul 的 JSON。第一次请求会下载选定的公开 Hugging Face checkpoint;不需要账号。首次下载请留出几分钟。 权重留在具名卷里。之后的运行用 docker compose run --rm laya。

预测结果和置信度仍需在你自己的工作负载上评估。见 基准限制。

ARM64 主机、DGX Spark 和 Apple Silicon 见 ARM64 与 DGX Spark 容器。

NVIDIA GPU / CUDA

装好兼容的 NVIDIA 驱动,并用 NVIDIA Container Toolkit 配置 Docker。GPU 镜像使用 PyTorch CUDA 13.0 wheel。对照 PyTorch 支持的构建检查你 GPU 的计算能力和驱动; 较老的卡可能需要另一种构建。为 CUDA 层预留额外的磁盘空间。显存需求取决于 checkpoint、批大小 和输入长度。

docker compose -f compose.yaml -f compose.cuda.yaml run --build --rm laya

这个 override 选择 GPU 0,并把 LAYA_DEVICE=cuda 设为默认。把 LAYA_GPU_ID 设为另一个 主机索引或 UUID。那块 GPU 在容器内显示为设备 0。不下权重也能检查访问是否正常:

docker compose -f compose.yaml -f compose.cuda.yaml run --rm laya python -c \
  'import torch; assert torch.cuda.is_available(); print(torch.cuda.get_device_name(0)); print(torch.ones(1, device="cuda").cpu())'

示例在加载 checkpoint 之前会先拒绝不可用的 CUDA。遇到内存或推理错误后,Laya 仍可能回退到 CPU,所以要留意它的警告。在 CPU 和 CUDA 配置之间切换时要重新构建。

镜像设置了 TORCH_DISABLE_NATIVE_JIT=1。否则 PyTorch 2.14 会把一些 eager CUDA 算子替换成 Triton 内核,并在第一次推理时编译它们,而这需要一个 slim 镜像里没有的 C 编译器:容器报告健康, 然后每个请求都失败(#365)。原装内核给出同样的答案、同样的延迟。裸机安装如果 predict 报 Failed to find C compiler,也请设置同一个变量。

这里用的是 Compose GPU 预留。Windows 需要 Docker Desktop 支持的 WSL2 GPU 设置。Apple MPS、AMD/ROCm 和 Intel GPU 容器不在这个快速 开始范围内;除非你另外配置并验证了后端,否则请用 CPU。

配置

在 shell、本地 .env 文件或服务的 environment 块里设置 Compose 变量。不要把密钥提交进 .env。运行时变量也可以通过 docker run -e 使用;仅限 Compose 的设置下面会标出。

变量 默认值 用途
LAYA_DEVICE cpu / cuda 由基础 / GPU 配置选择的设备
LAYA_CUDA_AMP 未设置(checkpoint 的 amp_dtype) CUDA 前向用 fp16/float16 或 bf16/bfloat16;其他任何值都被忽略。不是装饰性的:README 的阈值一节测出,在 fp16 一次 argmax 都不翻转的对等集上,bf16 翻转了 864 个中的 3 个
LAYA_CPU_AMP 未设置 bf16 或 bfloat16 让 CPU 前向使用 bf16;其他任何值都保持 fp32。任何 fp16 写法也打不开它:CPU autocast 没有比 fp32 更快的 fp16 快速路径,所以 bf16 是 core 在这个设备上提供的唯一降精度选项
LAYA_MODEL auto Router 别名:auto、english、multilingual、typed-decisions
LAYA_MODEL_PATH 未设置 容器内兼容的 checkpoint 路径
LAYA_REVISION 未设置 每次 checkpoint 下载所使用的 Hub commit、分支或 tag,或 reviewed 表示用 laya/revisions.py 里经过复核的 SHA;revision= 参数仍然优先
LAYA_REQUEST_FILE 内置请求 容器内的 JSON 请求路径
OMP_NUM_THREADS 4 CPU 线程数;不要超过可用核心
HF_TOKEN / HF_TOKEN_FILE 未设置 可选的 Hugging Face 凭据
LAYA_API_KEY / LAYA_API_KEY_FILE 未设置 仅 laya-serve: 要求 Authorization: Bearer <key>
LAYA_PORT 8000 仅 laya-serve: 容器端口,以及为它发布的宿主机端口
HF_HUB_OFFLINE 0 1 表示只用缓存的 checkpoint
HF_HOME /home/laya/.cache/huggingface 缓存路径;见下面的挂载要求
LAYA_CACHE_VOLUME 项目模型缓存 仅 Compose: 具名缓存卷
LAYA_GPU_ID 0 仅 Compose: NVIDIA 设备索引或 UUID
LAYA_TORCH_INDEX cu130(CUDA)/ cpu Compose 构建: PyTorch wheel 索引。cu126 也带着固定的 torch;cu128 不带
LAYA_TORCH_VERSION 2.14.0 Compose 构建: 固定的 PyTorch 版本

Compose 会转发运行时变量,但 HF_HOME 除外 —— 它与固定的缓存挂载保持一致;LAYA_MPS_AMP_MIN_ROWS (MPS 行数门限)也除外,因为这里没有任何镜像能触及它,这里也没有容器能选中 MPS。如果在 docker run 或你自己的 Compose 文件里覆盖 HF_HOME,请提供一个配套的、UID 10001 可写的 挂载。直接 Docker 构建用 --build-arg TORCH_INDEX=cu130 选择 PyTorch;运行时的 -e 改不了已 安装的 wheel。

LAYA_MODEL=english OMP_NUM_THREADS=2 docker compose run --build --rm laya

docker build -t laya:local .
docker run --rm -e LAYA_MODEL=english -e OMP_NUM_THREADS=2 \
  -v laya-model-cache:/home/laya/.cache/huggingface laya:local

用你自己的请求:

docker compose run --rm --volume "$PWD/request.json:/inputs/request.json:ro" \
  --env LAYA_REQUEST_FILE=/inputs/request.json laya

要看一份带注释、挂载了请求、checkpoint 和密钥文件的配置,见 compose.example.yml:

docker compose -f compose.yaml -f compose.example.yml run --build --rm laya

NVIDIA GPU 在 run 前加上 -f compose.cuda.yaml。这个示例是 compose.yaml 的 override, 所以缓存和镜像设置只放在一处。

密钥文件

HF_TOKEN_FILE 在启动时读取一个挂载的 UTF-8 文件,去掉首尾空白,优先级高于 HF_TOKEN。 读不到、为空或非法的文件会阻止启动,且不打印其内容。该文件必须对 UID 10001 可读。_FILE 只 适用于受支持的密钥,不是每项设置都行。

当 HF_TOKEN_PATH 指向 checkout 之外一个已存在的宿主机文件时:

docker compose run --rm --volume "$HF_TOKEN_PATH:/run/secrets/hf_token:ro" \
  --env HF_TOKEN_FILE=/run/secrets/hf_token laya

Docker secrets 或 Kubernetes Secret 卷也能提供同一个文件。值在启动时载入进程环境;改文件后需 重启。绝不要把 token 用作构建参数或烤进镜像里。公开 checkpoint 不需要 token。

微调后的 checkpoint

这个镜像跑推理。微调在它之外进行 —— 微调 notebook 在 Kaggle 免费的 2xT4 GPU 上跑完整个循环,导出一个这个镜像能服务的 checkpoint。关于训练接口的 背景和待决问题留在 #4 和 #26。

把 LAYA_CHECKPOINT_PATH 指向一个绝对宿主机目录,里面要有 rl_agent_config.json、 model.safetensors 和匹配的 tokenizer 文件:

docker compose run --rm --volume "$LAYA_CHECKPOINT_PATH:/models/custom" \
  --env LAYA_MODEL_PATH=/models/custom laya

请用 UID 10001 可写的工作副本,因为加载器可能会更新 tokenizer 配置。单有 LoRA 适配器不算一个 完整的 checkpoint。设置 LAYA_MODEL_PATH 时把 LAYA_MODEL=auto 留着;显式别名和本地路径互不 相容。本地路径的响应来自 Agent,没有 Router 的 routing 元数据。这些设置对 CUDA override 也 适用。请在留出样本上评估微调后的 checkpoint,再决定是否依赖它。

从 ModelScope 获取模型

当主机无法访问 huggingface.co 时,checkpoint 可以来自 ModelScope,并在构建时烤进镜像。用一个参数选择哪个 checkpoint, 默认是多语言那个。Compose override 会把预取参数加到两个服务上,并让容器不碰 Hub:

docker compose -f compose.yaml -f compose.http.yaml -f compose.modelscope.yaml up --build laya-serve

NVIDIA 的话,在 up 前加上 -f compose.cuda.yaml;它自己会为两个服务重复参数,所以两个 override 的先后顺序无所谓。直接用 Docker 则直接接受这些参数:

docker build --build-arg MODELSCOPE_MODEL=multilingual \
  -t laya:local .
docker run --rm -e HF_HUB_OFFLINE=1 -p 127.0.0.1:8000:8000 laya:local laya-serve

对之前跑过它的主机有一个前提。烤进去的权重要落在镜像内的 $HF_HOME/hub,也就是 compose.yaml 把 model-cache 卷挂载到的那个缓存目录(/home/laya/.cache/huggingface) 下,而 Docker 只在该具名卷为空时才从镜像为它播种。一个从基于 Hub 的快速开始遗留下来的卷 握着旧的 Hub 快照,它永远不会被重新播种,烤进去的权重就藏在它后面看不见:加载器把 refs/main 解析到旧的 Hub commit,容器用已经下载过的权重作答,就好像这次重建什么都没改。 把部署指向一个空的缓存卷 —— 用同样的 Compose 文件和同样的 LAYA_CACHE_VOLUME 运行 docker compose down --volumes,或用 LAYA_CACHE_VOLUME=<name> 换一个全新的。设了 HF_HUB_OFFLINE=1 时,缺失或分叉的 ref 就是一次加载失败,没有网络可以回退,但这个前提是 一样的。

docker/prefetch_modelscope.py 列出 modelscope.cn 上的仓库,下载 checkpoint 自己的文件 —— 也就是 laya/agent.py 向 Hub 要的同一组,所以不会拉取兄弟 checkpoint —— 并按 snapshot_download 铺开快照的方式把它们 写进镜像的 hub 缓存。其他什么都不变:Agent、laya-serve 构建的 Router、laya.cli 以及各集成都保留自己的 repo id,并把它们解析到烤进去的快照,所以这样构建的容器完全不需要 网络。每个文件的大小会在快照发布之前对照仓库报告的值检查,仓库发布摘要时连 SHA-256 也一起 查。大小或摘要对不上会让构建失败。仓库不发布摘要时,检查就只剩大小,而这检测不出同样大小 的替换。

变量 默认值 用途
MODELSCOPE_MODEL multilingual(Compose);Dockerfile 里为空 要烤哪个 checkpoint:multilingual、english、typed-decisions 或 all。为空表示不预取,镜像不变
MODELSCOPE_REVISION master 要烤的 ModelScope 分支、tag 或 commit
HF_HUB_OFFLINE Compose override 里为 1 1 从不联系 Hub,所以提供的是烤进去的那份

一个类型会展开为该 checkpoint 在捆绑仓库内的路径,也就是 Router 和一次性快速开始默认 加载的那个,所以一个只指定了某个类型的构建无需进一步改动就能提供它:

MODELSCOPE_MODEL=english docker compose -f compose.yaml -f compose.http.yaml -f compose.modelscope.yaml up --build laya-serve
MODELSCOPE_MODEL=all docker compose -f compose.yaml -f compose.http.yaml -f compose.modelscope.yaml up --build laya-serve

all 是整个家族,约 2.4 GB 权重。这个 override 还会设 LAYA_MODELS=multilingual,因为 LAYA_PRELOAD=1 配上默认列表会试图构建每个 checkpoint,并在第一个没烤进去的上面失败;当 你烤了更多时,把 LAYA_MODELS 设成你烤的那个列表,当部署确实要提供整个家族时再设 MODELSCOPE_MODEL=all。

可以一次指定多个类型 —— MODELSCOPE_MODEL="english multilingual" 会两个都烤,约 1.5 GB —— 这通常正是服务镜像想要的:Router 自己在英语和多语言 checkpoint 之间选择,而它没拿到 的那个会用日志里的 does not contain 'rl_agent_config.json' 回答 500 inference failed。 共享一个仓库的 checkpoint 总是烤进同一个快照,因为一个缓存的 revision 只解析到一个目录; 根 checkpoint 和每个子目录都在里面。

除了类型,这个参数还接受 repo[:subfolder] 形式的规格,逗号或空格分隔,镜像的独立仓库 (laya、 laya-multilingual、 laya-typed-decisions) 或一个微调后的 checkpoint 就是这样烤的。独立仓库是 Agent("convaiinnovations/laya-multilingual") 直接加载的东西;Router 的默认是捆绑路径, 所以服务镜像通常要的是类型。

关于固定和来源的两个细节。构建会打印快照以之键控的 commit,也就是所烤 revision 的顶端 —— 把那个 SHA 作为 revision= 或 LAYA_REVISION 传入,就能把加载精确固定到所烤的东西上。一个 镜像仓库可以装着来自多次上传的文件,所以那个顶端是唯一存在的仓库级键。Hub 侧的固定不描述 镜像快照:reviewed 命名的是 Hugging Face commit,而 SHA-256 摘要映射以 Hub 制品哈希为键, 所以两者在这里都不适用,镜像快照也不存在摘要固定。构建已经会拒绝与镜像自己报告的大小不符的 下载 —— 镜像发布摘要时也拒绝摘要不符的 —— 但这检查的是与镜像元数据的一致性,不是一个独立 固定的摘要。权重来自参数所命名的那个镜像账号,那是部署自己要做的供应链决定。

开发与清理

用 docker compose run --rm laya python 打开一个 Python 提示符。想在不下载权重的情况下,对 你的 checkout 跑现有的路由/判定标准检查和密钥文件测试:

docker compose run --rm --volume "$PWD:/workspace:ro" --workdir /workspace laya \
  sh -ec 'python tests/test_router.py; python tests/test_criteria.py; python tests/test_docker_entrypoint.py'

改动源码或内置示例后,用 --build 重新构建。镜像以 UID/GID 10001 运行。新建的具名卷继承镜像 缓存目录的属主;宿主机目录必须对该 UID 可写。模型缓存要保持可写,以便做 tokenizer 兼容性更新。

--rm 会删除已完成的容器。docker compose down 保留缓存。要删除已下载的权重,用同样的 Compose 文件和 LAYA_CACHE_VOLUME 设置运行 docker compose down --volumes。下一个请求会重新 下载它们;不要删掉与其他项目共享的缓存。

HTTP 服务

镜像自带 laya-serve,所以跑一次性快速开始的那次构建也能提供兼容 Jev 的 API。 compose.http.yaml 把它加为第二个服务,不动 laya:

docker compose -f compose.yaml -f compose.http.yaml up --build laya-serve
curl -s localhost:8000/health
curl -s localhost:8000/v1/systemone -H 'content-type: application/json' \
  --data @examples/docker/request.json

NVIDIA 再叠上 CUDA override。它要为 laya-serve 重复构建参数和设备预留,因为 laya-serve 是一个单独的服务,针对 laya 的 override 到不了它:

docker compose -f compose.yaml -f compose.http.yaml -f compose.cuda.yaml up --build laya-serve

up 让服务在前台运行;-d 转到后台。权重进到和快速开始同一个具名的 model-cache 卷,所以 快速开始跑过之后再起服务,checkpoint 已经在磁盘上了。用同样的 Compose 文件,通过 docker compose ... down 停止。

端口只在 127.0.0.1 上发布。在设置 LAYA_API_KEY 之前 API 没有认证,所以用 LAYA_BIND_ADDRESS=0.0.0.0 暴露它之前先设一个 key,并为远程客户端在前面放一个 TLS 反向 代理。两种情况下 /health 都不需要认证,所以下面的健康检查照常工作;设置 key 后,它对未经 认证的调用者回答 {"status": "ok"},并保留需要 bearer 的 checkpoint、revision 和 device 字段。

服务对 /health 有健康检查。服务器在开始监听前先预加载,所以 LAYA_PRELOAD=1 时,一个健康的 容器其 checkpoint 已经加载好了。docker compose ... up -d --wait laya-serve 会在它健康后 返回。

/health 报告的 device 是常驻 checkpoint 实际计算所用的设备,它不总是 LAYA_DEVICE 要求的 那个:一个想要 GPU 却拿不到的 checkpoint 会静默回退到 CPU,仍然给出正确的答案。 checkpoint_devices 列出每个已加载的 checkpoint,device_is_preference 只在没有任何常驻 checkpoint 时为 true,于是一个悄悄丢了 GPU 的部署会说出来,而不是把自己配置里的东西原样 回声。

服务器配置

这些只适用于 laya-serve 服务。

变量 默认值 作用
LAYA_HOST 0.0.0.0 容器内的绑定地址
LAYA_PORT 8000 容器端口,以及为它发布的宿主机端口
LAYA_BIND_ADDRESS 127.0.0.1 端口发布所在的宿主机地址
LAYA_PRELOAD 0 1 表示启动时就构建每个 checkpoint,而不是首次请求时
LAYA_MODELS (全部) 要预加载的逗号列表:english,multilingual,typed-decisions
LAYA_THREADS OMP_NUM_THREADS 限制 torch 进程内线程数;保持在物理核心数或以下
LAYA_AUTO_TASK 0 1 让路由器能自动触达 typed-decisions
LAYA_DEFAULT_MODEL multilingual 没有语言证据的 state 回退到哪个 checkpoint(没有字母,或拉丁文本短到无法识别)。主要是英语流量时设为 english;无法解析的名字会在启动时停住容器,而不是提供一个没人要的配置
LAYA_EXTRA_MODELS (无) JSON 对象 {name: source},在捆绑的 checkpoint 之外注册额外的 checkpoint:源可以是一个 Hub repo id 或本地 checkpoint 目录(字符串),或一个 ["repo", "subfolder"] 对
LAYA_IDLE_UNLOAD_SECONDS 0 空闲这么多秒后卸载常驻的 checkpoint;下一个请求会再次加载它的 checkpoint。零表示禁用卸载
LAYA_MAX_LOADED 2 保持常驻的 checkpoint 数;LAYA_AUTO_TASK 让第三个可按需触达,而上限低于路由实际选择时,每次切换都会重建一个
LAYA_MAX_CONCURRENT 16 一次可接纳的请求数;更晚的会拿到 503(无法解析或非正数的值会回退到 16)
LAYA_LOG_LEVEL info uvicorn 日志级别
LAYA_API_KEY (无) 设置后要求 Authorization: Bearer <key>
LAYA_ROOT_PATH (空) 在反向代理之后时,FastAPI 的公开 URL 前缀;代理应在转发前把它剥掉
LAYA_MAX_TOKEN_BUDGET 8192 对每请求 max_len 和 head_max_len 覆盖的上限
LAYA_MAX_BATCH_TOKENS 131072 一次 /v1/systemone/batch 前向传播可以拼合的 token 数(states × questions × 行宽);更大的批次会被拆成几趟,而不是被拒绝
LAYA_JEV_STRICT 0 1 为严格的 Jev 客户端提供严格的 Jev 线上契约(根上无 routing,每个答案无 action / answer_confidence,usage 缩减)
LAYA_SHA256_DIGESTS (无) 在解析 checkpoint 之前校验的 JSON 摘要:对所有 checkpoint 是 {artifact: digest},对每个 checkpoint 是 {model: {artifact: digest}}。见安全

比如,在 /laya 下发布 API 时,设置 LAYA_ROOT_PATH=/laya。代理必须在转发到容器之前剥掉这个 前缀;这项设置更新 FastAPI 生成的 URL,不改变内部的 /health 或 /v1/systemone 路由。

LAYA_PRELOAD 这里默认是 0,而不是包默认的 1,因为预加载会让首次启动下载全部三个 checkpoint。长时间运行的部署把它设为 1,这样第一个请求不用为构建买单。

LAYA_PORT 同时设置发布的宿主机端口和服务器绑定的端口,所以两者不会脱节。要挪动服务,只改 一处:

LAYA_PORT=9000 docker compose -f compose.yaml -f compose.http.yaml up --build laya-serve

从文件读 bearer token

LAYA_API_KEY_FILE 在启动时读一次,移入 LAYA_API_KEY,然后在服务器 exec 之前删掉 _FILE 变量。优先用它,而不是把 key 放进环境:

docker compose -f compose.yaml -f compose.http.yaml run --rm \
  --volume "$PWD/laya_api_key:/run/secrets/laya_api_key:ro" \
  -e LAYA_API_KEY_FILE=/run/secrets/laya_api_key \
  --service-ports laya-serve