[gerardo-navarro]

Summary

Users in networks without access to Hugging Face, or behind a proxy that inspects TLS, currently have no guide for getting the models in place. #318 showed several pitfalls that are easy to hit by hand.

New page docs/offline-model-install.md:

• which models are needed (large-v3-turbo, speaker-detection only for speaker detection) and where they go (MSIX, Flatpak, from source, ATRAIN_USER_DIR, redirected Documents folder)
• a PowerShell script that downloads the pinned revisions with exact file names and subfolders, using the Windows proxy and certificate store
• browser pitfalls: .gitattributes saved without the dot, pytorch_model (1).bin suffixes
• a required checksum check against models.json, since aTrain verifies only its own downloads, never hand-copied files
• what aTrain does with incomplete folders, per version (up to rc5 the folder is deleted when Hugging Face is unreachable or HF_HUB_OFFLINE=1; later versions keep it), and a warning about the "Download" button for a hand-installed speaker-detection
• proxies that inspect TLS: the CERTIFICATE_VERIFY_FAILED error, and a CA bundle workaround that sets both REQUESTS_CA_BUNDLE (up to rc5) and SSL_CERT_FILE (Hub 1.33 and later)

Linked from docs/README.md and the requirements in docs/deployment-windows.md.

Note: the TLS section assumes #319 (truststore) ships. If this merges first, "aTrain versions that verify against the Windows certificate store" refers to the upcoming release.

References

Refs #318, related to #319

Screenshots / Examples

n/a (docs only)

Verification Steps

• Revisions, repos and file lists in the script match aTrain_core/data/models.json on develop (checked by script).
• Behaviour described under "What aTrain does with incomplete folders" was reproduced in a Windows 11 VM with mitmproxy as TLS-inspecting proxy (see Manual offline install of required models on Windows (MSIX) fails: hash mismatch and attempted Hugging Face access #318) and on Linux for rc3, rc5 and develop (see review comment).
• Run the PowerShell download script and the checksum snippet on Windows 11 behind a TLS-inspecting proxy and confirm aTrain transcribes without contacting Hugging Face.
• Run the CA bundle snippet on Windows and confirm a download from the models page works.

[BW-Projects]

@gerardo-navarro With #286 merged, parts of the page no longer match develop. I tested rc3, rc5 and develop on Linux with a hand-copied large-v3-turbo and no access to Hugging Face.

• Incomplete folders: Up to rc5, aTrain deletes the folder when Hugging Face is unreachable or HF_HUB_OFFLINE=1 is set. It keeps the folder only on a certificate error. develop now keeps the folder in every case and only shows the error.
• Checksums: aTrain only verifies its own downloads, never hand-copied files. Get-FileHash should be a required step until aTrain checks hand-copied models itself.
• Models page: it lists a hand-installed speaker-detection as not downloaded and offers "Download". Without access to Hugging Face, that click deletes the folder. Worth a warning. I can open an issue for it.
• Certificates: develop (Hub 1.33) reads SSL_CERT_FILE instead of REQUESTS_CA_BUNDLE. Setting both covers all versions.

[gerardo-navarro]

@BW-Projects Thanks for testing. All four points are in 527a72b:

• Incomplete folders: a table per version, "up to 1.5.0-rc5" vs. "later versions".
• Checksums: now a required step, with a snippet that reads the expected SHA-256 values from models.json and lists missing or wrong files.
• Models page: warning not to click "Download" for a hand-installed speaker-detection without access to Hugging Face. An issue for the listing itself would be good, please go ahead.
• Certificates: the snippet sets both REQUESTS_CA_BUNDLE and SSL_CERT_FILE.

[BW-Projects]

@gerardo-navarro I ran the download script in a Windows 11 VM behind a TLS-inspecting proxy. It stops at the first file: Windows PowerShell 5.1, the version Windows 11 ships, rejects -ProxyUseDefaultCredentials without -Proxy. The switch never takes effect without -Proxy there, so dropping it loses nothing. Without the switch, Invoke-WebRequest uses the Windows proxy settings and the script downloads all files. My test proxy needed no login, so I could not check a proxy that asks for the Windows login. The checksum and CA snippets worked there with a Windows build of #286.

[gerardo-navarro]

@BW-Projects Thanks, fixed in 13eec94: the switch is gone. For proxies that ask for the Windows login, the script now sets [System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials before the downloads. Not tested against such a proxy yet.