容器镜像服务 AI 模型管理

本文向您介绍如何使用 modctl CLI 管理您的 AI 模型：构建、推送、拉取、版本管理。TCR（腾讯云容器镜像服务）AI 模型管理功能，让您可以像管理容器镜像一样管理 AI 模型。模型以 OCI Artifact 格式存储，支持版本管理、分发加速等企业级能力。
说明：
本文档描述的功能由 TCR 服务端 + modctl CLI 组合实现。TCR 提供模型存储、查询、版本管理等服务端能力，modctl 提供本地构建、推送、拉取等客户端能力。
核心概念
概念
说明
modctl
AI 模型管理 CLI 工具，支持模型的构建、推送、拉取。
Modelfile
模型描述文件，定义模型的名称、类型、包含的文件。
OCI Artifact
开放容器倡议制品格式，模型打包后的标准格式。
命名空间
模型的逻辑分组，如 ai-team、nlp-models。
安装 CLI 工具
Linux / macOS（二进制下载）
# Linux / macOS（直接下载二进制）
MODCTL_VERSION="0.0.1"
OS=$(uname -s | tr '[:upper:]' '[:lower:]')  
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/arm64/arm64/')
curl -fsSL "https://github.com/modelpack/modctl/releases/download/v${MODCTL_VERSION}/modctl-${MODCTL_VERSION}-${OS}-${ARCH}.tar.gz" \\
  | tar -xz -C /usr/local/bin modctl
chmod +x /usr/local/bin/modctl
登录 TCR 实例
TCR 支持临时登录指令和用户级账号和服务级账号类型，请根据您的场景选择：
1. 获取临时登录指令或用户级访问凭证、服务级账号访问凭证
1. 登录 容器镜像服务控制台。
2. 在左侧导航栏中的访问凭证中，选择用户级账号或服务级账号。
用户级账号：可选创建临时访问凭证，或生成长期访问凭证。详细配置信息请参见 用户级账号管理。
服务级账号：单击新建，创建服务级账号访问凭证。详细配置信息请参见 服务级账号管理。
3. 创建完成后，查看您的访问凭证（用户名 + 长期密码）。
2. 复制登录命令
控制台会生成两种登录指令，请根据您使用的工具复制对应的命令：
Docker 登录（用于容器镜像推拉）：
docker login agent-pilot.tencentcloudcr.com --username xxxx --password xxxx
modctl 登录（用于 AI 模型管理）：
modctl login agent-pilot.tencentcloudcr.com --username xxxx --password xxxx
说明：
两种工具使用相同的用户名和密码，只是命令不同。
3. 执行登录
# 粘贴从控制台复制的 modctl 登录指令
modctl login agent-pilot.tencentcloudcr.com --username xxxx --password xxxx
﻿
# 期望输出
# Login Succeeded.
上传模型到 TCR
Step 1: 准备模型文件
确保您的模型目录包含以下文件：
my-model/
├── config.json          # 模型配置（必需）
├── model.safetensors    # 模型权重（必需）
├── tokenizer.json       # 分词器配置（可选）
├── tokenizer_config.json
└── README.md            # 模型说明（可选）
支持的模型格式：
SafeTensors (推荐)
PyTorch (.bin)
ONNX (.onnx)
GGUF (.gguf)
Step 2: 生成 Modelfile
cd my-model
﻿
# 自动识别文件类型，生成 Modelfile
modctl modelfile generate . \\
  --name my-llama-model \\
  --family llama \\
  --output .
﻿
# 期望输出
# Generating modelfile for .
# Successfully generated modelfile
参数说明：
参数
说明
示例
--name
模型名称
my-llama-model
--family
模型家族（llama/qwen/gpt2/bert 等）
llama
--format
权重格式
safetensors
--param-size
参数量
7b、13b、70b
--precision
精度
fp16、bf16、int8
--output
输出目录
.
查看生成的 Modelfile：
cat Modelfile
﻿
# 输出示例：
# NAME my-llama-model
# FAMILY llama
# CONFIG config.json
# MODEL model.safetensors
# DOC README.md
Step 3: 构建 OCI Artifact
# 构建模型（指定完整的镜像地址和版本号）
modctl build . \\
  -f ./Modelfile \\
  -t tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0
﻿
# 期望输出
# Building layer => config.json  | 2.3 kB | done(0.0s)
# Built layer => sha256:abc123...
# Building layer => model.safetensors  | 15.2 GB | done(45.2s)
# Built layer => sha256:def456...
# Successfully built model artifact: tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0
镜像地址格式：
{registry}/{namespace}/{model-name}:{version}
registry：TCR 实例域名。
namespace：命名空间（需提前创建）。
model-name：模型名称。
version：版本号（建议使用语义化版本）。
Step 4: 推送到 TCR
modctl push tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0
﻿
# 期望输出
# Copying blob => sha256:abc123... | 2.3 kB | done(0.1s)
# Copying blob => sha256:def456... | 15.2 GB | done(120.5s)
# Copying config => sha256:789xyz...
# Copying manifest => sha256:manifest123...
# Successfully pushed model artifact: tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0
完整示例脚本
#!/bin/bash
# upload-model.sh - 上传模型到 TCR 的完整脚本
﻿
# 配置
REGISTRY="tcr-prod.tencentcloudcr.com"
NAMESPACE="ai-team"
MODEL_NAME="my-llama-model"
VERSION="v1.0.0"
MODEL_DIR="./my-model"
﻿
# 完整地址
REPO="$REGISTRY/$NAMESPACE/$MODEL_NAME:$VERSION"
﻿
echo "📦 开始上传模型到 TCR..."
echo "目标地址: $REPO"
﻿
# 1. 生成 Modelfile
echo "🔧 Step 1: 生成 Modelfile..."
modctl modelfile generate $MODEL_DIR \\
  --name $MODEL_NAME \\
  --family llama \\
  --output $MODEL_DIR
﻿
# 2. 构建
echo "🏗️ Step 2: 构建 OCI Artifact..."
modctl build $MODEL_DIR \\
  -f $MODEL_DIR/Modelfile \\
  -t $REPO
﻿
# 3. 推送
echo "⬆️ Step 3: 推送到 TCR..."
modctl push $REPO
﻿
echo "✅ 上传完成！"
echo "拉取命令: modctl pull $REPO"
从 TCR 下载模型
方式一：完整下载
# 1. 拉取模型到本地缓存
modctl pull tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0
﻿
# 期望输出
# Pulling blob => sha256:abc123... | done(0.1s)
# Pulling blob => sha256:def456... | done(45.2s)
# Successfully pulled model artifact
﻿
# 2. 解压到指定目录
modctl extract tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0 \\
  --output ./downloaded-model
﻿
# 期望输出
# Successfully extracted model artifact to ./downloaded-model
﻿
# 3. 查看解压结果
ls ./downloaded-model
# config.json  model.safetensors  README.md
方式二：选择性下载（节省带宽）
当模型文件很大时，可以只下载需要的文件：
# 只下载配置文件（快速查看模型信息）
modctl fetch tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0 \\
  --output ./config-only \\
  --patterns "*.json"
﻿
# 只下载模型权重
modctl fetch tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0 \\
  --output ./weights-only \\
  --patterns "*.safetensors"
﻿
# 下载多种类型文件
modctl fetch tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0 \\
  --output ./partial \\
  --patterns "*.json,*.md"
方式三：查看模型信息（不下载）
# 查看模型元数据
modctl inspect tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0
﻿
# 输出示例（JSON 格式）
# {
#     "Id": "sha256:config123...",
#     "Digest": "sha256:manifest123...",
#     "Family": "llama",
#     "Name": "my-llama-model",
#     "Layers": [
#         {
#             "MediaType": "application/vnd.cncf.model.weight.config.v1.raw",
#             "Digest": "sha256:abc123...",
#             "Size": 2300,
#             "Filepath": "config.json"
#         },
#         {
#             "MediaType": "application/vnd.cncf.model.weight.v1.raw",
#             "Digest": "sha256:def456...",
#             "Size": 15200000000,
#             "Filepath": "model.safetensors"
#         }
#     ]
# }
完整示例脚本
#!/bin/bash
# download-model.sh - 从 TCR 下载模型的完整脚本
﻿
# 配置
REGISTRY="tcr-prod.tencentcloudcr.com"
NAMESPACE="ai-team"
MODEL_NAME="my-llama-model"
VERSION="v1.0.0"
OUTPUT_DIR="./models/$MODEL_NAME"
﻿
# 完整地址
REPO="$REGISTRY/$NAMESPACE/$MODEL_NAME:$VERSION"
﻿
echo "📥 开始下载模型..."
echo "来源地址: $REPO"
echo "目标目录: $OUTPUT_DIR"
﻿
# 1. 拉取
echo "⬇️ Step 1: 拉取模型..."
modctl pull $REPO
﻿
# 2. 解压
echo "📦 Step 2: 解压模型..."
mkdir -p $OUTPUT_DIR
modctl extract $REPO --output $OUTPUT_DIR
﻿
# 3. 验证
echo "✅ 下载完成！文件列表："
ls -lh $OUTPUT_DIR
版本管理
查看本地模型列表
modctl ls
﻿
# 输出示例
# REPOSITORY                                            TAG       DIGEST        CREATED        SIZE
# tcr-prod.tencentcloudcr.com/ai-team/my-llama-model    v1.0.0    sha256:abc... 2h ago         15.2 GB
# tcr-prod.tencentcloudcr.com/ai-team/my-llama-model    v1.1.0    sha256:def... 30m ago        15.5 GB
为模型打标签
# 为现有模型添加新标签
modctl tag tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0 \\
  tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:latest
﻿
# 推送新标签
modctl push tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:latest
追加文件到现有模型
# 向已有模型追加文件（如 tokenizer）
modctl attach ./tokenizer_config.json \\
  -s tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0 \\
  -t tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.1
﻿
# 推送新版本
modctl push tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.1
删除本地模型
# 删除指定版本
modctl rm tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0
﻿
# 清理无用数据
modctl prune
常用命令速查
操作
命令
安装 CLI
brew install modctl 或 npm install -g modctl
登录
modctl login $REGISTRY --username $USER --password $TOKEN
登出
modctl logout $REGISTRY
生成 Modelfile
modctl modelfile generate ./model --name NAME --family FAMILY --output .
构建
modctl build ./model -f ./Modelfile -t $REPO:$TAG
推送
modctl push $REPO:$TAG
拉取
modctl pull $REPO:$TAG
解压
modctl extract $REPO:$TAG --output ./output
选择性下载
modctl fetch $REPO:$TAG --output ./output --patterns "*.json"
查看详情
modctl inspect $REPO:$TAG
列表
modctl ls
打标签
modctl tag $SOURCE $TARGET
追加文件
modctl attach FILE -s $SOURCE -t $TARGET
删除
modctl rm $REPO:$TAG
清理
modctl prune
常见问题
Q1: 登录失败，提示 "unauthorized"
可能原因：
1. 用户名或密码错误。
2. Token 已过期。
3. 没有该命名空间的权限。
解决方案：
# 检查凭证是否正确
echo $REGISTRY_USER
echo $REGISTRY_TOKEN
﻿
# 重新登录
modctl logout $REGISTRY
modctl login $REGISTRY --username $REGISTRY_USER --password $REGISTRY_TOKEN
Q2: 推送失败，提示 "namespace not found"
可能原因：命名空间不存在。
解决方案：
1. 登录 容器镜像服务 控制台。
2. 选择左侧导航栏中的命名空间，在命名空间页面单击新建。
3. 在新建命名空间页面，配置命名空间信息并单击确认。需要确保您有该命名空间的写入权限。
Q3: 构建很慢，有什么优化方法？
建议：
1. 使用 SafeTensors 格式（比 .bin 更快）。
2. 大模型考虑先压缩再上传。
3. 检查网络带宽。
Q4: 如何查看远程仓库的模型列表？
目前 modctl 主要管理本地模型列表，查看远程仓库请使用容器镜像服务控制台。
Q5: 模型太大，下载中断怎么办？
modctl 支持断点续传，重新执行 modctl pull 即可从断点继续。
能力边界说明
当前能力
能力
说明
模型以 OCI Artifact 格式存储
支持 CNAI model artifact media type
模型上传 / 拉取
通过 modctl CLI + TCR 服务端组合实现
模型版本管理
基于 OCI tag 机制
模型列表查询
TCR 服务端 API 支持
模型版本详情
包含 Framework、TaskType、Precision、FileFormat 等
推荐版本标记
基于 recommended tag 机制
相关文档
﻿容器镜像服务控制台使用指南﻿
﻿AI Skills 管理指南﻿
﻿modctl GitHub 仓库﻿
﻿
﻿
﻿

参数	说明	示例
`--name`	模型名称	`my-llama-model`
`--family`	模型家族（llama/qwen/gpt2/bert 等）	`llama`
`--format`	权重格式	`safetensors`
`--param-size`	参数量	`7b`、`13b`、`70b`
`--precision`	精度	`fp16`、`bf16`、`int8`
`--output`	输出目录	`.`

操作	命令
安装 CLI	`brew install modctl` 或 `npm install -g modctl`
登录	`modctl login $REGISTRY --username $USER --password $TOKEN`
登出	`modctl logout $REGISTRY`
生成 Modelfile	`modctl modelfile generate ./model --name NAME --family FAMILY --output .`
构建	`modctl build ./model -f ./Modelfile -t $REPO:$TAG`
推送	`modctl push $REPO:$TAG`
拉取	`modctl pull $REPO:$TAG`
解压	`modctl extract $REPO:$TAG --output ./output`
选择性下载	`modctl fetch $REPO:$TAG --output ./output --patterns "*.json"`
查看详情	`modctl inspect $REPO:$TAG`
列表	`modctl ls`
打标签	`modctl tag $SOURCE $TARGET`
追加文件	`modctl attach FILE -s $SOURCE -t $TARGET`
删除	`modctl rm $REPO:$TAG`
清理	`modctl prune`

概念	说明
modctl	AI 模型管理 CLI 工具，支持模型的构建、推送、拉取。
Modelfile	模型描述文件，定义模型的名称、类型、包含的文件。
OCI Artifact	开放容器倡议制品格式，模型打包后的标准格式。
命名空间	模型的逻辑分组，如 `ai-team`、`nlp-models`。

能力	说明
模型以 OCI Artifact 格式存储	支持 CNAI model artifact media type
模型上传 / 拉取	通过 modctl CLI + TCR 服务端组合实现
模型版本管理	基于 OCI tag 机制
模型列表查询	TCR 服务端 API 支持
模型版本详情	包含 Framework、TaskType、Precision、FileFormat 等
推荐版本标记	基于 `recommended` tag 机制

AI 模型管理

本页目录：

核心概念

安装 CLI 工具

Linux / macOS（二进制下载）

登录 TCR 实例

1. 获取临时登录指令或用户级访问凭证、服务级账号访问凭证

2. 复制登录命令

3. 执行登录

上传模型到 TCR

Step 1: 准备模型文件

Step 2: 生成 Modelfile

Step 3: 构建 OCI Artifact

Step 4: 推送到 TCR

完整示例脚本

从 TCR 下载模型

方式一：完整下载

方式二：选择性下载（节省带宽）

方式三：查看模型信息（不下载）

完整示例脚本

版本管理

查看本地模型列表

为模型打标签

追加文件到现有模型

删除本地模型

常用命令速查

常见问题

Q1: 登录失败，提示 "unauthorized"

Q2: 推送失败，提示 "namespace not found"

Q3: 构建很慢，有什么优化方法？

Q4: 如何查看远程仓库的模型列表？

Q5: 模型太大，下载中断怎么办？

能力边界说明

当前能力

相关文档