容器镜像服务 AI 模型管理

注意：说明：

注意：这篇档描述的功能由 TCR 服务端 + modctl CLI 组合实现。TCR 提供模型存储、查询、版本管理等服务端能力，modctl 提供本地构建、推送、拉取等客户端能力。

一、核心概念

三、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 modctlchmod +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.

九、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# 自动识别文件类型，生成 Modelfilemodctl modelfile generate . \\ –name my-llama-model \\ –family llama \\ –output .# 期望输出# Generating modelfile for .# Successfully generated modelfile

参数说明：

查看生成的 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. 生成 Modelfileecho " 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 $REPOecho "✅ 上传完成！"echo "拉取命令: modctl pull $REPO"

十五、方式一：完整下载

# 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_DIRmodctl extract $REPO –output $OUTPUT_DIR# 3. 验证echo "✅ 下载完成！文件列表："ls -lh $OUTPUT_DIR

20、查看本地模型列表

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

21、为模型打标签

# 为现有模型添加新标签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

22、追加文件到现有模型

# 向已有模型追加文件（如 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

23、删除本地模型

# 删除指定版本modctl rm tcr-prod.tencentcloudcr.com/ai-team/my-llama-model:v1.0.0# 清理无用数据modctl prune

24、常用命令速查

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

可能原因：

1. 用户名或密码错误。

2. Token 已过期。

3. 没有该命名空间的权限。

解决方案：

# 检查凭证是否正确echo $REGISTRY_USERecho $REGISTRY_TOKEN# 重新登录modctl logout $REGISTRYmodctl login $REGISTRY –username $REGISTRY_USER –password $REGISTRY_TOKEN

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

可能原因：命名空间不存在。

解决方案：

1. 登录 容器镜像服务 控制台。

2. 选择左侧导航栏中的命名空间，在命名空间页面单击新建。

3. 在新建命名空间页面，配置命名空间信息并单击确认。需要确保你有该命名空间的写入权限。

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

建议：

1. 使用 SafeTensors 格式（比 .bin 更快）。

2. 大模型考虑先压缩再上传。

3. 检查网络带宽。

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

目前 modctl 主要管理本地模型列表，查看远程仓库请使用容器镜像服务控制台。

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

modctl 支持断点续传，重新执行 modctl pull 即可从断点继续。

32、当前能力

33、相关文档

·容器镜像服务控制台使用指南

·AI Skills 管理指南

·modctl GitHub 仓库