fromHuggingFace method
Set model source from a Hugging Face repo. Two modes:
Explicit file (pass file): builds
https://huggingface.co/<repo>/resolve/<revision>/<file> and installs it
via the network path. file may contain / for a repo that nests
variants in subfolders (e.g. int4/model.litertlm); each segment is
URL-encoded independently so the path structure survives. Use this when
you know the exact path (and optionally a pinned revision).
Manifest (one-call) (OMIT file): resolves the repo's deployment
manifest internally at install time — via the resolver registered for
this builder's fileType (see FlutterEdgeAi.resolveHuggingFace) — then
installs the resolved, revision-pinned variant and returns the manifest's
overridable runtime defaults on InferenceInstallation.runtime:
final install = await FlutterEdgeAi
.installModel(modelType: ModelType.general, fileType: ModelFileType.litertlm)
.fromHuggingFace('org/repo') // no file — resolve the manifest
.install();
final model = await FlutterEdgeAi.getActiveModel(defaults: install.runtime);
Notes on the manifest mode:
revisionmust be left'main': the registered resolver owns the pin (it builds a revision-pinned URL). Passing a non-'main'revisionwithout afilethrows ArgumentError.- The resolver's own behavior surfaces from install:
.onnxresolves and installs an ORT-GenAI model DIRECTORY (via the HF file tree), while.builtInthrowsUnsupportedError(the OS owns the weights — there is no Hugging Face file) — naming the repo. - Unlike other sources, this requires NETWORK access at install even if
the model is already installed (the variant filename is only known after
the manifest fetch). For offline-safe idempotent installs, cache the
ResolvedHfModelyourself and install fromfromNetwork(r.url). modelType: passModelType.generalto let the manifest decide the family; pass a SPECIFIC type to keep your choice (it wins over the manifest, and any disagreement is surfaced in InferenceInstallation.notes).- A CancelToken set via
withCancelTokencannot interrupt the manifest fetch itself (the resolver takes no token); cancellation is honoured immediately after the fetch returns, before the download starts.
The plugin already applies the configured HuggingFace token to
huggingface.co URLs for gated repos, so token is only needed to
override it (it is also threaded into the manifest fetch).
Implementation
InferenceInstallationBuilder fromHuggingFace(
String repo, {
String? file,
String revision = 'main',
String? token,
bool? foreground,
}) {
// Fail loud at the seam — an empty repo would otherwise build a URL that
// only 404s (or, worse, saves a CDN error page as the model) far downstream.
if (repo.trim().isEmpty) {
throw ArgumentError.value(repo, 'repo', 'must be a non-empty "org/name"');
}
if (file == null) {
// Manifest mode: defer resolution to install(). The resolver builds the
// revision-pinned URL, so a caller-supplied non-'main' revision here has
// nowhere to go — reject it loudly rather than silently dropping the pin.
if (revision != 'main') {
throw ArgumentError.value(
revision,
'revision',
'cannot be set without an explicit `file`: the registered resolver '
'owns the revision pin. Pass `file:` to install a specific path '
'at a specific revision, or register the resolver with the '
'revision you want.',
);
}
_clearSource();
_modelSource = null; // cancel any earlier explicit source
_hfRepo = repo;
_hfToken = token;
_hfForeground = foreground;
return this;
}
if (file.trim().isEmpty) {
throw ArgumentError.value(
file,
'file',
'must be a non-empty repo-relative path (or omit `file` to resolve the '
'repo manifest)',
);
}
final encodedPath = file.split('/').map(Uri.encodeComponent).join('/');
final url = 'https://huggingface.co/$repo/resolve/$revision/$encodedPath';
return fromNetwork(url, token: token, foreground: foreground);
}