download: add option to skip_download

[ngxson]

Overview

Add a new flag skip_download to the common_params_handle_models function. This is a clean up for the upcoming model download / management API (cc @allozaur ). It is useful to know if a download is required before running a model.

Its meaning:

• offline = false --> normal case, ETag is validated and if mismatch, redownload the GGUF
• offline = false and skip_download = true --> validation will be performed, but skip download if ETag mismatch
• offline = true --> no validation or download will be performed (also implies skip_download)

Note:

• I wanted to expose this as a new need_download field in /v1/models, but it takes too much time to validate the ETag, so in the end I did not add it. Probably will revisit this in another PR.

Requirements

• I have read and agree with the contributing guidelines
• AI usage disclosure: no

[ngxson]

hey @angt , can you have a quick look at this PR? thanks!

[angt]

I think skip_download should also skip the download if the file doesn't exist ?

[ngxson]

hmm yes that was my intention, file not found is the same as ETag mismatch case, right? (or maybe I missed something?)

[angt]

Maybe i badly tested it 🤔

I did this:

$ git df
diff --git a/common/arg.cpp b/common/arg.cpp
index 85ef58296..61e7dfa8c 100644
--- a/common/arg.cpp
+++ b/common/arg.cpp
@@ -347,7 +347,7 @@ static handle_model_result common_params_handle_model(struct common_params_model
     common_download_opts opts;
     opts.bearer_token  = params.hf_token;
     opts.offline       = params.offline;
-    opts.skip_download = params.skip_download;
+    opts.skip_download = true; //params.skip_download;

     if (!model.docker_repo.empty()) {
         model.path = common_docker_resolve_model(model.docker_repo);
diff --git a/common/download.cpp b/common/download.cpp
index 5a5704fe1..aa50a8337 100644
--- a/common/download.cpp
+++ b/common/download.cpp
@@ -287,6 +287,10 @@ static int common_download_file_single_online(const std::string & url,
                                               const std::string & path,
                                               const common_download_opts & opts,
                                               bool skip_etag) {
+    if (opts.skip_download) {
+        LOG_WRN("SKIP DOWNLOAD\n");
+    }
+
     static const int max_attempts        = 3;
     static const int retry_delay_seconds = 2;

and got:

$ LLAMA_CACHE=nothing ./build/bin/llama-server -hf unsloth/Qwen3.5-0.8B-GGUF
0.00.104.406 W SKIP DOWNLOAD
0.00.104.481 W SKIP DOWNLOAD
Downloading mmproj-BF16.gguf ─────────────────────────────────────── 100%
Downloading Qwen3.5-0.8B-Q4_K_M.gguf ─────────────────────────────── 100%

[ngxson]

@angt I addressed the problem in ec6a687 , could you take a look? Thanks!

[ngxson]

I need to merge this to unblock some other task. @angt could you review & give the 2nd approval?

[ggerganov]

@ngxson This change caused a regression in the use case where we load a separate MTP draft model file. I use this command:

./bin/llama serve \
  -hf ggml-org/Qwen3.6-35B-A3B-GGUF:Q8_0 \
  --spec-type draft-mtp \
  --spec-draft-hf ggml-org/Qwen3.6-35B-A3B-GGUF \
  --spec-draft-model mtp-Qwen3.6-35B-A3B-Q4_0.gguf

After this change, something causes the mtp- model file to be downloaded two times at the same time:

Which later leads to corruption of the data: