# modelscope-go

**Repository Path**: zhReimu/modelscope-go

## Basic Information

- **Project Name**: modelscope-go
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# modelscope-go

`modelscope-go` 是一个面向 ModelScope 的 Go 下载 SDK，并附带 Kong 驱动的 `ms` 命令行工具。它支持模型和数据集、断点续传、并发快照下载、文件过滤、离线缓存、Token 鉴权和显式 Git/LFS 克隆。

## 安装

```shell
go get gitee.com/zhReimu/modelscope-go
go install gitee.com/zhReimu/modelscope-go/cmd/ms@latest
```

项目开发任务由 [Taskfile](https://taskfile.dev/) 管理：

```shell
task fmt
task vet
task test
task build
```

## SDK

客户端选项可配置 Endpoint、Token、HTTP 超时、重试次数、并发数、User-Agent、自定义 `http.Client` 和默认缓存目录。

```go
package main

import (
	"context"
	"fmt"
	"log"

	modelscope "gitee.com/zhReimu/modelscope-go"
)

func main() {
	client, err := modelscope.NewClient(
		modelscope.WithToken("your-token"),
		modelscope.WithConcurrency(8),
	)
	if err != nil {
		log.Fatal(err)
	}

	dir, err := client.DownloadSnapshot(
		context.Background(),
		"Qwen/Qwen3-0.6B",
		modelscope.RepoTypeModel,
		modelscope.DownloadOptions{
			Revision: "master",
			Include:  []string{"*.json", "**/*.safetensors"},
			Exclude:  []string{"original/**"},
			Progress: func(event modelscope.ProgressEvent) {
				fmt.Printf("%s %s %d/%d\n", event.Status, event.FilePath, event.CompletedBytes, event.TotalBytes)
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(dir)
}
```

下载单个文件：

```go
path, err := client.DownloadFile(
	context.Background(),
	"Qwen/Qwen3-0.6B",
	modelscope.RepoTypeModel,
	"README.md",
	modelscope.DownloadOptions{Revision: "master"},
)
```

设置 `LocalFilesOnly: true` 后不会发起网络请求，仅返回已有的新布局或旧版兼容缓存；缓存缺失时返回 `ErrOfflineCacheMiss`。

## CLI

```shell
# 保存 Token
ms login --token YOUR_TOKEN

# 下载模型快照（model 是默认类型）
ms download Qwen/Qwen3-0.6B --revision master

# 下载指定文件
ms download Qwen/Qwen3-0.6B README.md configuration.json

# 下载数据集并过滤文件
ms download owner/dataset --dataset --include "**/*.jsonl" --exclude "private/**" --max-workers 8

# 直接写入指定目录；下划线别名 --local_dir 同样可用
ms download owner/repo --local-dir ./model
```

CLI 支持 `--model`、`--dataset`、`--revision`、`--cache-dir`/`--cache_dir`、`--local-dir`/`--local_dir`、`--include`、`--exclude`、`--max-workers`、`--token` 和 `--endpoint`。成功时向标准输出打印结果路径，失败时向标准错误输出脱敏错误并返回非零退出码。

Token 的读取优先级为显式客户端/CLI 参数、`MODELSCOPE_API_TOKEN` 环境变量、登录后持久化的用户配置。也可用 `MODELSCOPE_CONFIG_DIR` 改写配置目录。请求同时发送 `Authorization: Bearer` 和 `m_session_id` Cookie，以兼容不同版本的 ModelScope 接口。

## 缓存布局

默认缓存目录是操作系统用户缓存目录下的 `modelscope`。可通过 `MODELSCOPE_CACHE`、客户端选项或下载选项覆盖。

```text
{cache}/
  models|datasets/
    owner--name/
      snapshots/
        revision/
          repository/files...
```

读取离线缓存时也兼容旧布局：

```text
{cache}/{models|datasets}/{owner}/{name 中的 . 替换为 ___}/...
```

指定 `LocalDir` 时优先于缓存目录，仓库相对路径会直接保留在该目录中。下载中的文件使用 `.incomplete` 后缀，并通过文件锁防止多进程重复下载。

## Git/LFS 克隆

`Clone` 是独立接口，不是 REST 下载失败时的自动回退。本机必须安装 `git` 和 Git LFS，并先执行过 `git lfs install`。

```go
err := client.Clone(
	context.Background(),
	"Qwen/Qwen3-0.6B",
	modelscope.RepoTypeModel,
	"./Qwen3-0.6B",
	modelscope.CloneOptions{Revision: "master", Depth: 1},
)
```

Token 仅通过 Git 子进程环境传递，库返回的错误会进行脱敏。Git、LFS、鉴权和 revision 错误可分别用 `errors.Is` 判断 `ErrGitNotInstalled`、`ErrLFSNotInstalled`、`ErrAuthentication` 和 `ErrRevisionNotFound`。

## 测试策略

默认测试全部使用 `httptest.Server`，不会访问外网。应用可以在自己的 CI 中另行添加由环境变量显式启用的真实 ModelScope 集成测试。

## 代码结构

根包是稳定的公共门面，调用方仍直接导入 `gitee.com/zhReimu/modelscope-go`。具体实现位于 `internal`，不会扩大对外 API：

```text
modelscope-go/
├── modelscope.go          # 稳定公共门面，仅导出类型、常量和薄包装函数
├── internal/
│   ├── sdk/               # 客户端组装、公共配置与用例适配
│   ├── domain/            # 仓库、文件、进度与校验规则
│   ├── download/          # 下载用例、并发编排与过滤
│   ├── transport/         # ModelScope HTTP API
│   ├── cache/             # 缓存布局、哈希与文件锁
│   ├── credentials/       # Token 持久化
│   └── gitrepo/           # Git/LFS 子进程适配
└── cmd/ms/                # Kong CLI
```