gijl/lv-storage / llama.cpp /tools /ui /src /lib /services /huggingface.service.ts
gijl's picture
download
raw
26.4 kB
import { PATH_SEPARATOR, SETTINGS_KEYS } from '$lib/constants';
import {
BYTE,
BYTE_LABEL,
DAYS_AGO_LABEL,
DAYS_PER_MONTH,
DAYS_PER_WEEK,
DAYS_PER_YEAR,
GIGA_LABEL,
GIGABYTE,
GIGABYTE_LABEL,
HF_API_MODELS_URL,
HF_AVATARS_URL,
HF_BASE_MODEL_TAG_REGEX,
HF_BASE_URL,
HF_CACHE_DIR_SEPARATOR,
HF_CACHE_PATH_REGEX,
HF_DECISION_MODEL_TAG,
HF_DECISION_PIPELINE_TAG,
HF_DEFAULT_LIMIT,
HF_FIRST_SHARD,
HF_FRONTMATTER_REGEX,
HF_FULL_DETAIL_PARAM,
HF_GATED_TAG,
HF_GGUF_FILTER,
HF_GGUF_TAG,
HF_HTTP_NOT_FOUND,
HF_HTTP_SERVER_ERROR_MIN,
HF_LICENSE_TAG_PREFIX,
HF_LINK_HEADER,
HF_LINK_NEXT_REGEX,
HF_MAIN_BRANCH,
HF_MAX_LIMIT,
HF_MODEL_LIST_EXPAND,
HF_PARAM_COUNT_REGEX,
HF_QUANT_PRECISION_REGEX,
HF_RAW_PATH,
HF_README_FILENAME,
HF_RECURSIVE_TREE_PARAM,
HF_RETRY_ATTEMPTS,
HF_RETRY_DELAY_MS,
HF_SAFETENSORS_TAG,
HF_SHARD_PAD_WIDTH,
HF_SHARD_REGEX,
HF_SHARED_DRAFT_TOKEN,
HF_SIZE_STRING_REGEX,
HF_SIZE_SUFFIX_BYTES,
HF_TASK_TAGS,
HF_TREE_MAX_PAGES,
HF_TREE_PATH,
HF_UD_QUANT_PREFIX,
HF_UD_QUANT_PREFIX_REGEX,
KILO_LABEL,
KILOBYTE,
KILOBYTE_LABEL,
MEGA_LABEL,
MEGABYTE,
MEGABYTE_LABEL,
MODELS_DISCOVER_CATALOG_URL,
MONTHS_AGO_LABEL,
MS_PER_DAY,
TODAY_LABEL,
WEEKS_AGO_LABEL,
YEARS_AGO_LABEL,
YESTERDAY_LABEL
} from '$lib/constants';
import { MODEL_ID, type ModelSidecar } from '$lib/constants';
import { HfEntryType, HfModelSort, SidecarForm } from '$lib/enums';
import { settingsStore } from '$lib/stores/settings/index.svelte';
import type {
HfCatalogEntry,
HfModelDetailInfo,
HfModelInfo,
HfModelSearchParams,
HfModelSibling
} from '$lib/types/huggingface';
import { sidecarFromFileToken } from '$lib/utils';
import { SvelteMap } from 'svelte/reactivity';
/** Fetch failure carrying the HTTP status, so retry logic tests the code instead of the message. */
class HfHttpStatusError extends Error {
status: number;
constructor(status: number, statusText: string) {
super(`API request failed: ${status} ${statusText}`);
this.status = status;
}
}
export class HuggingFaceService {
private static readonly BASE_URL = HF_API_MODELS_URL;
// Cached base model lookups keyed by repo id, so repeated selector opens
// never re-hit the HF API for the same repo.
private static baseModelCache = new Map<string, { org: string; name: string } | null>();
private static baseModelPending = new Map<
string,
Promise<{ org: string; name: string } | null>
>();
// Model details fetched this session, keyed by repo id: the Hub rate limits
// aggressively, so each repo costs at most one request per load. Failures stay
// uncached so the next mount can retry.
private static detailsCache = new SvelteMap<string, HfModelDetailInfo | null>();
private static detailsPending = new Map<string, Promise<HfModelDetailInfo | null>>();
/**
* Map of quant token to its average bit-depth in bits-per-weight (bpw).
*/
private static readonly QUANT_BIT_DEPTH: Record<string, number> = {
BF16: 16,
F16: 16,
IQ1_M: 1,
IQ1_S: 1,
IQ1_XS: 1,
IQ1_XXS: 1,
IQ2_M: 2,
IQ2_S: 2,
IQ2_XS: 2,
IQ2_XXS: 2,
IQ3_M: 3,
IQ3_S: 3,
IQ3_XS: 3,
IQ3_XXS: 3,
Q2_K: 2,
Q2_K_M: 2,
Q2_K_S: 2,
Q3_K: 3,
Q3_K_L: 3,
Q3_K_M: 3,
Q3_K_S: 3,
Q4_0: 4,
Q4_1: 4,
Q4_K: 4,
Q4_K_M: 4,
Q4_K_S: 4,
Q5_0: 5,
Q5_1: 5,
Q5_K: 5,
Q5_K_M: 5,
Q5_K_S: 5,
Q6_K: 6,
Q8_0: 8
};
// File trees already fetched, keyed by repo id: the discover view asks for the same
// repo from several places.
private static treeCache = new Map<string, HfModelSibling[]>();
private static treePending = new Map<string, Promise<HfModelSibling[]>>();
/** Details already fetched, for a caller that cannot await (a table sorting its rows). */
static cachedDetails(modelId: string): HfModelDetailInfo | null | undefined {
// llama.cpp model ids carry the quant tag after a colon
const [hfRepoId] = modelId.split(MODEL_ID.QUANTIZATION_SEPARATOR);
return HuggingFaceService.detailsCache.get(hfRepoId);
}
// GGUF Model Browsing
/**
* Collapse split GGUF shard sets (`-00001-of-00015.gguf`, ...) to their first
* shard, summing every shard's size so the kept entry reflects the whole
* quant. Downloads are tag-based (`repo:quant`), so the first shard is
* enough to represent the set.
*/
static collapseGgufShards(siblings: HfModelSibling[]): HfModelSibling[] {
const sizeByPath = new Map(siblings.map((f) => [f.path, f.size ?? 0]));
const result: HfModelSibling[] = [];
for (const file of siblings) {
const match = HF_SHARD_REGEX.exec(file.path);
if (!match) {
result.push(file);
continue;
}
if (Number(match[1]) !== HF_FIRST_SHARD) continue;
const total = Number(match[2]);
const stem = file.path.slice(0, file.path.length - match[0].length);
let size = 0;
for (let i = HF_FIRST_SHARD; i <= total; i++) {
const shard = HuggingFaceService.shardPath(stem, i, total);
size += sizeByPath.get(shard) ?? 0;
}
result.push({ ...file, size });
}
return result;
}
/**
* Extract the GGUF quantization token (e.g. `Q4_K_M`) and any sidecar type
* (`mtp`, `dflash`, `mmproj`, ...) from a `.gguf` filename.
*
* `sidecarForm` records which side of the filename the sidecar token sat on
* so callers can render badges differently. `quant` and `sidecar` are `null`
* when absent; returns `null` for non-GGUF filenames.
*/
static extractQuantMeta(filename: string): {
quant: string | null;
/** Draft-head-only variant borrowing embed/output weights from the target model. */
shared: boolean;
sidecar: ModelSidecar | null;
sidecarForm: SidecarForm | null;
} | null {
if (!MODEL_ID.WEIGHT_EXTENSION_REGEX.test(filename)) return null;
// HF repos may nest sidecars in a folder (e.g. `MTP/mtp-Model-Q4_0.gguf`);
// parse the file name only, the folder adds no quant information.
let source = (filename.split(PATH_SEPARATOR).pop() ?? filename).replace(
MODEL_ID.WEIGHT_EXTENSION_REGEX,
''
);
let sidecar: ModelSidecar | null = null;
let sidecarForm: SidecarForm | null = null;
// A file named just the sidecar token (`imatrix.gguf`) is the sidecar
// itself: no name or quant segments to parse.
const bareSidecar = sidecarFromFileToken(source.toLowerCase());
if (bareSidecar) {
return { quant: null, shared: false, sidecar: bareSidecar, sidecarForm: SidecarForm.PREFIX };
}
const prefixMatch = source.match(MODEL_ID.SIDECAR_PREFIX_REGEX);
if (prefixMatch) {
sidecar = sidecarFromFileToken(prefixMatch[1].toLowerCase());
sidecarForm = SidecarForm.PREFIX;
source = prefixMatch[2];
} else {
const suffixMatch = source.match(MODEL_ID.SIDECAR_SUFFIX_REGEX);
if (suffixMatch) {
// Take the suffix sidecar even when the head carries no quant:
// embedded drafts end in one (`Hy3-IQ1_M-mtp`), standalone sidecar
// files do not (`Model-mtp-draft`, `Model-imatrix`).
sidecar = sidecarFromFileToken(suffixMatch[2].toLowerCase());
sidecarForm = SidecarForm.SUFFIX;
source = suffixMatch[1];
} else {
const infixMatch = source.match(MODEL_ID.SIDECAR_INFIX_REGEX);
if (infixMatch) {
sidecar = sidecarFromFileToken(infixMatch[2].toLowerCase());
sidecarForm = SidecarForm.INFIX;
source = `${infixMatch[1]}-${infixMatch[3]}`;
}
}
}
// Scan dash-separated segments left-to-right for the first quant match.
// - For sidecars like `mtp-Q4_0-180MB.gguf` the quant is `Q4_0`.
// - For embedded MTP like `Hy3-IQ1_M-mtp.gguf` we have `Hy3-IQ1_M` and `IQ1_M` matches.
// - For main files like `Llama-3-8B-Q4_K_M.gguf` we land on the trailing quant.
const segments = source.split(MODEL_ID.SEGMENT_SEPARATOR);
const quantIdx = segments.findIndex((seg) => MODEL_ID.QUANTIZATION_SEGMENT_REGEX.test(seg));
// Unsloth ships draft heads in two layouts: `shared-` files borrow the
// embedding/output weights from the target model, others are self-contained.
const shared = segments.some((seg) => seg.toLowerCase() === HF_SHARED_DRAFT_TOKEN);
let quant = quantIdx >= 0 ? segments[quantIdx].toUpperCase() : null;
// Recombine a `UD-` (Unsloth Dynamic) prefix, e.g. `...-UD-Q4_K_XL.gguf`.
// The prefix must be the whole previous segment, matching the server's
// `UD-<quant>` custom-quant convention (e.g. not `-mtp-Q4_K_M`).
const udPrefixIdx = quantIdx - 1;
if (quant && quantIdx > 0 && segments[udPrefixIdx].toUpperCase() === HF_UD_QUANT_PREFIX) {
quant = `${HF_UD_QUANT_PREFIX}-${quant}`;
}
return { quant, shared, sidecar, sidecarForm };
}
static filterByExtension(siblings: HfModelSibling[], ext: string): HfModelSibling[] {
return siblings
.filter((f) => f.path.toLowerCase().endsWith(ext.toLowerCase()) && (f.size ?? 0) > 0)
.sort((a, b) => (b.size ?? 0) - (a.size ?? 0));
}
static formatDownloads(downloads: number): string {
if (downloads >= GIGABYTE) {
return `${(downloads / GIGABYTE).toFixed(1)}${GIGA_LABEL}`;
}
if (downloads >= MEGABYTE) {
return `${(downloads / MEGABYTE).toFixed(1)}${MEGA_LABEL}`;
}
if (downloads >= KILOBYTE) {
return `${(downloads / KILOBYTE).toFixed(1)}${KILO_LABEL}`;
}
return downloads.toString();
}
static formatFileSize(bytes: number): string {
if (bytes >= GIGABYTE) {
return `${(bytes / GIGABYTE).toFixed(1)} ${GIGABYTE_LABEL}`;
}
if (bytes >= MEGABYTE) {
return `${(bytes / MEGABYTE).toFixed(1)} ${MEGABYTE_LABEL}`;
}
if (bytes >= KILOBYTE) {
return `${(bytes / KILOBYTE).toFixed(1)} ${KILOBYTE_LABEL}`;
}
return `${bytes} ${BYTE_LABEL}`;
}
static formatLikes(likes: number): string {
if (likes >= KILOBYTE) {
return `${(likes / KILOBYTE).toFixed(1)}${KILO_LABEL}`;
}
return likes.toString();
}
static formatRelativeTime(timestamp: string): string {
const date = new Date(timestamp);
const now = new Date();
const diffMs = now.getTime() - date.getTime();
// timestamps can lie in the future (clock skew); clamp so they read as today
const diffDays = Math.max(0, Math.floor(diffMs / MS_PER_DAY));
if (diffDays === 0) return TODAY_LABEL;
if (diffDays === 1) return YESTERDAY_LABEL;
if (diffDays < DAYS_PER_WEEK) return `${diffDays} ${DAYS_AGO_LABEL}`;
if (diffDays < DAYS_PER_MONTH) {
return `${Math.floor(diffDays / DAYS_PER_WEEK)} ${WEEKS_AGO_LABEL}`;
}
if (diffDays < DAYS_PER_YEAR) {
return `${Math.floor(diffDays / DAYS_PER_MONTH)} ${MONTHS_AGO_LABEL}`;
}
return `${Math.floor(diffDays / DAYS_PER_YEAR)} ${YEARS_AGO_LABEL}`;
}
// Model Details & Files
/**
* Format a min-max size range with one shared unit, e.g. `19.0-28.6 GB`.
*/
static formatSizeRange(min: number, max: number): string {
const unit =
max >= GIGABYTE
? GIGABYTE_LABEL
: max >= MEGABYTE
? MEGABYTE_LABEL
: max >= KILOBYTE
? KILOBYTE_LABEL
: BYTE_LABEL;
const div =
unit === GIGABYTE_LABEL
? GIGABYTE
: unit === MEGABYTE_LABEL
? MEGABYTE
: unit === KILOBYTE_LABEL
? KILOBYTE
: BYTE;
const fmt = (n: number) => (div === BYTE ? `${n}` : `${(n / div).toFixed(1)}`);
return `${fmt(min)}-${fmt(max)} ${unit}`;
}
/**
* Avatar URL for an author (org or user). 404s when the author does not
* exist, so callers should provide a fallback.
*/
static getAvatarUrl(author: string): string {
// OpenRouter-style model ids prefix the provider with a tilde
// (`~openai/gpt-...`); the avatars endpoint only resolves bare names
return `${HF_AVATARS_URL}${PATH_SEPARATOR}${author.replace(/^~/, '')}`;
}
/**
* Resolve the original (non-GGUF) base model `{ org, name }` for a GGUF repo
* from its HF card (`cardData.base_model`). Returns null when the card has no
* base model. A resolved repo is cached for the session.
*/
static getBaseModel(repoId: string): Promise<{ org: string; name: string } | null> {
if (!HuggingFaceService.isEnabled()) return Promise.resolve(null);
// all quants of one repo share the cached lookup, so key it by the repo id
const [hfRepoId] = repoId.split(MODEL_ID.QUANTIZATION_SEPARATOR);
const cached = this.baseModelCache.get(hfRepoId);
if (cached !== undefined) return Promise.resolve(cached);
const pending = this.baseModelPending.get(hfRepoId);
if (pending) return pending;
const promise = (async () => {
const details = await this.getDetails(hfRepoId);
const base = this.getBaseModels(details)[0];
if (!base) return null;
const [org, ...rest] = base.split(PATH_SEPARATOR);
return { name: rest.join(PATH_SEPARATOR), org };
})();
this.baseModelPending.set(hfRepoId, promise);
promise
// a repo with no base model stays uncached: the details behind it are cached
// already, so a retry costs nothing and a failed lookup can try again
.then((result) => {
if (result) this.baseModelCache.set(hfRepoId, result);
})
.finally(() => this.baseModelPending.delete(hfRepoId));
return promise;
}
/**
* Extract the original (non-GGUF) base model ids for a repo, from
* `cardData.base_model` (string or list) and the `base_model:` tags.
*/
static getBaseModels(model: HfModelDetailInfo | null): string[] {
if (!model) return [];
const cardBase = model.cardData?.base_model;
const fromCard: string[] = Array.isArray(cardBase) ? cardBase : cardBase ? [cardBase] : [];
const fromTags = (model.tags ?? [])
.map((t) => HF_BASE_MODEL_TAG_REGEX.exec(t)?.[1])
.filter((v): v is string => Boolean(v));
return Array.from(new Set([...fromCard, ...fromTags]));
}
/**
* Look up the average bit-depth for a known GGUF quantization.
* Returns `null` for unrecognized tokens.
*/
static getBitDepth(quant: string): number | null {
const base = quant.replace(HF_UD_QUANT_PREFIX_REGEX, '');
const direct = HuggingFaceService.QUANT_BIT_DEPTH[base];
if (direct !== undefined) return direct;
// Fall back to the leading precision digits for variants missing from the
// map, e.g. `Q4_K_XL` -> 4, `IQ2_XXS` -> 2, `TQ1_0` -> 1, `BF16` -> 16.
const match = HF_QUANT_PRECISION_REGEX.exec(base);
return match ? parseInt(match[1], 10) : null;
}
static async getByTask(
pipelineTag: string,
params: Omit<HfModelSearchParams, 'pipeline_tag'> = {}
): Promise<HfModelInfo[]> {
return this.search({
...params,
pipeline_tag: pipelineTag
});
}
static async getCatalog(): Promise<HfCatalogEntry[]> {
if (!HuggingFaceService.isEnabled()) return [];
const response = await fetch(MODELS_DISCOVER_CATALOG_URL);
if (!response.ok) throw new Error(`Failed to fetch catalog: ${response.status}`);
const entries = (await response.json()) as HfCatalogEntry[];
return entries.filter((entry) => !entry.decision);
}
static getDetails(modelId: string): Promise<HfModelDetailInfo | null> {
if (!HuggingFaceService.isEnabled()) return Promise.resolve(null);
const cached = HuggingFaceService.detailsCache.get(modelId);
if (cached !== undefined) return Promise.resolve(cached);
const pending = HuggingFaceService.detailsPending.get(modelId);
if (pending) return pending;
const promise = (async () => {
// Do not encode the modelId, it contains slashes for author/name.
// `full=true` includes cardData (description, base_model) and safetensors.
const url = `${HF_API_MODELS_URL}${PATH_SEPARATOR}${modelId}?${HF_FULL_DETAIL_PARAM}`;
try {
const response = await fetch(url);
// a missing model is a definitive answer, cache it
if (response.status === HF_HTTP_NOT_FOUND) {
HuggingFaceService.detailsCache.set(modelId, null);
return null;
}
if (!response.ok) throw new Error(`Failed to fetch model details: ${response.status}`);
// the hub answers with a list of provider entries for one repo; the gguf and
// card data sit on the entry that carries them
const payload = (await response.json()) as HfModelDetailInfo | HfModelDetailInfo[];
const entries = Array.isArray(payload) ? payload : [payload];
const data = entries.find((entry) => entry?.gguf ?? entry?.cardData) ?? entries[0];
if (!data) return null;
HuggingFaceService.detailsCache.set(modelId, data);
return data;
} catch (error) {
// not cached: a rate limited or failed fetch retries on the next mount
// instead of hiding the model for the session
console.error(`Error fetching details for ${modelId}:`, error);
return null;
} finally {
HuggingFaceService.detailsPending.delete(modelId);
}
})();
HuggingFaceService.detailsPending.set(modelId, promise);
return promise;
}
static getModelUrl(modelId: string): string {
return `${HF_BASE_URL}${PATH_SEPARATOR}${modelId}`;
}
// Utility Methods
static async getMostLiked(limit: number = HF_DEFAULT_LIMIT): Promise<HfModelInfo[]> {
return this.search({ limit, sort: HfModelSort.LIKES });
}
static async getNew(limit: number = HF_DEFAULT_LIMIT): Promise<HfModelInfo[]> {
return this.search({ limit, sort: HfModelSort.CREATED_AT });
}
static async getPopular(limit: number = HF_DEFAULT_LIMIT): Promise<HfModelInfo[]> {
return this.search({ limit, sort: HfModelSort.DOWNLOADS });
}
/**
* Fetch the raw README.md for a repo, with the YAML frontmatter stripped.
*/
static async getReadme(modelId: string): Promise<string | null> {
if (!HuggingFaceService.isEnabled()) return null;
// Do not encode the modelId, it contains slashes for author/name
const url = `${HF_BASE_URL}${PATH_SEPARATOR}${modelId}${PATH_SEPARATOR}${HF_RAW_PATH}${PATH_SEPARATOR}${HF_MAIN_BRANCH}${PATH_SEPARATOR}${HF_README_FILENAME}`;
try {
const response = await fetch(url);
if (response.status === HF_HTTP_NOT_FOUND) return null;
if (!response.ok) throw new Error(`Failed to fetch README: ${response.status}`);
return HuggingFaceService.stripFrontmatter(await response.text());
} catch (error) {
console.error(`Error fetching README for ${modelId}:`, error);
return null;
}
}
static getTree(modelId: string): Promise<HfModelSibling[]> {
if (!HuggingFaceService.isEnabled()) return Promise.resolve([]);
const cached = HuggingFaceService.treeCache.get(modelId);
if (cached) return Promise.resolve(cached);
const pending = HuggingFaceService.treePending.get(modelId);
if (pending) return pending;
const promise = (async () => {
const files: HfModelSibling[] = [];
const firstUrl =
`${HF_API_MODELS_URL}${PATH_SEPARATOR}${modelId}${PATH_SEPARATOR}${HF_TREE_PATH}` +
`${PATH_SEPARATOR}${HF_MAIN_BRANCH}?${HF_RECURSIVE_TREE_PARAM}`;
let url: string | null = firstUrl;
for (let page = 0; url && page < HF_TREE_MAX_PAGES; page++) {
const response: Response = await fetch(url);
if (!response.ok)
throw new Error(`Failed to fetch tree for ${modelId}: ${response.status}`);
const data = (await response.json()) as HfModelSibling[];
files.push(...data.filter((f) => f.type !== HfEntryType.DIRECTORY));
url = HuggingFaceService.parseNextPageUrl(response.headers.get(HF_LINK_HEADER));
}
HuggingFaceService.treeCache.set(modelId, files);
return files;
})()
.catch((error: unknown) => {
// not cached: a rate limited or failed fetch should retry on the
// next mount; an empty tree makes the store fall back to the
// catalog's advertised sizes
console.error(`Error fetching tree for ${modelId}:`, error);
return [] as HfModelSibling[];
})
.finally(() => HuggingFaceService.treePending.delete(modelId));
HuggingFaceService.treePending.set(modelId, promise);
return promise;
}
static async getTrending(limit: number = HF_DEFAULT_LIMIT): Promise<HfModelInfo[]> {
return this.search({ limit, sort: HfModelSort.TRENDING_SCORE });
}
/**
* True for decision models: they answer with calibrated probabilities instead
* of generated text, so llama-ui cannot use them and they stay out of every
* list the Hub data layer returns.
*/
static isDecisionModel(model: Pick<HfModelInfo, 'pipeline_tag' | 'tags'>): boolean {
return (
model.tags.includes(HF_DECISION_MODEL_TAG) || model.pipeline_tag === HF_DECISION_PIPELINE_TAG
);
}
/**
* True when the UI may read from the Hugging Face Hub API: model display data
* (avatars, context length, chat template) and the Discover Models view. With
* it off, callers only see what the server's /v1/models reports and the org
* avatars stay hidden.
*/
static isEnabled(): boolean {
return settingsStore.config[SETTINGS_KEYS.USE_HUGGING_FACE_HUB] ?? false;
}
/**
* Parameter count a repo reports: a GGUF repo spells it out in its metadata,
* a transformers repo reports it in its SafeTensors index.
*/
static parameterCount(details?: HfModelDetailInfo | null): number | null {
return details?.gguf?.total ?? details?.safetensors?.total ?? null;
}
/**
* Parse a local HF cache file path
* (`.../models--<org>--<name>/snapshots/<sha>/<file>`) into its repo id and
* repo-relative file path. Returns null when the path is not an HF cache path.
*/
static parseCachePath(path: string): { repo: string; file: string } | null {
// the paths come from the server's CLI args, which use native separators
const match = HF_CACHE_PATH_REGEX.exec(path.replace(/\\/g, PATH_SEPARATOR));
if (!match) return null;
const parts = match[1].split(HF_CACHE_DIR_SEPARATOR);
if (parts.length < 2) return null;
return {
file: match[2],
repo: `${parts[0]}${PATH_SEPARATOR}${parts.slice(1).join(HF_CACHE_DIR_SEPARATOR)}`
};
}
/**
* Best-effort parameter count parsed from a model id/name, e.g. `27B` from
* `Qwen3.8-27B-GGUF` or `300M` from `embeddinggemma-300M-GGUF`. Returns null
* when no size token is present.
*/
static parseParamCount(name: string): string | null {
const match = HF_PARAM_COUNT_REGEX.exec(name);
if (!match) return null;
return `${match[1]}${match[2].toUpperCase()}`;
}
/**
* Parse a human size string (`177GB`, `1.2 TB`, `500MB`) to bytes. Returns
* null when it carries no number or no known suffix, so callers can fall
* back to another source instead of showing a wrong size.
*/
static parseSizeBytes(size: string): number | null {
const match = HF_SIZE_STRING_REGEX.exec(size);
if (!match) return null;
const value = parseFloat(match[1]);
const multiplier = HF_SIZE_SUFFIX_BYTES[match[2].toLowerCase()];
if (!Number.isFinite(value) || multiplier === undefined) return null;
return value * multiplier;
}
static parseTags(tags: string[]): {
license: string | null;
isGated: boolean;
isGguf: boolean;
isSafetensors: boolean;
tasks: string[];
} {
const license =
tags
.find((tag) => tag.startsWith(HF_LICENSE_TAG_PREFIX))
?.replace(HF_LICENSE_TAG_PREFIX, '') || null;
const isGated = tags.includes(HF_GATED_TAG);
const isGguf = tags.includes(HF_GGUF_TAG);
const isSafetensors = tags.includes(HF_SAFETENSORS_TAG);
const tasks = tags.filter((tag) => HF_TASK_TAGS.includes(tag));
return { isGated, isGguf, isSafetensors, license, tasks };
}
/**
* Search GGUF models with various filters and options.
*
* Always expands the fields the discover rows render (chat template, context
* length, siblings, ...) so a search result carries the same badges as a
* catalog entry; caller-provided `expand` entries are merged in.
*/
static async search(params: HfModelSearchParams = {}): Promise<HfModelInfo[]> {
if (!HuggingFaceService.isEnabled()) return [];
const { expand, limit = HF_DEFAULT_LIMIT, ...restParams } = params;
const url = this.buildUrl({
...restParams,
expand: [...new Set([...HF_MODEL_LIST_EXPAND, ...(expand ?? [])])],
filter: HF_GGUF_FILTER,
limit: Math.min(limit, HF_MAX_LIMIT)
});
const models = await this.fetchWithRetry(url);
return models.filter((model) => !HuggingFaceService.isDecisionModel(model));
}
static async searchByQuery(
query: string,
params: Omit<HfModelSearchParams, 'search'> = {}
): Promise<HfModelInfo[]> {
return this.search({
...params,
search: query
});
}
private static buildUrl(params: HfModelSearchParams): string {
const url = new URL(this.BASE_URL);
Object.entries(params).forEach(([key, value]) => {
if (value !== undefined && value !== null && value !== '') {
if (Array.isArray(value)) {
value.forEach((v) => url.searchParams.append(key, v));
} else {
url.searchParams.set(key, String(value));
}
}
});
return url.toString();
}
private static delay(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
private static async fetchWithRetry(url: string, attempt: number = 1): Promise<HfModelInfo[]> {
try {
const response = await fetch(url);
if (!response.ok) {
if (response.status === HF_HTTP_NOT_FOUND) {
return [];
}
if (response.status >= HF_HTTP_SERVER_ERROR_MIN && attempt < HF_RETRY_ATTEMPTS) {
await this.delay(HF_RETRY_DELAY_MS * attempt);
return this.fetchWithRetry(url, attempt + 1);
}
throw new HfHttpStatusError(response.status, response.statusText);
}
const data = await response.json();
if (Array.isArray(data)) {
return data as HfModelInfo[];
}
if (data && Array.isArray(data.data)) {
return data.data as HfModelInfo[];
}
throw new Error('Unexpected API response format');
} catch (error) {
const transient =
error instanceof TypeError ||
(error instanceof HfHttpStatusError && error.status >= HF_HTTP_SERVER_ERROR_MIN);
if (transient && attempt < HF_RETRY_ATTEMPTS) {
await this.delay(HF_RETRY_DELAY_MS * attempt);
return this.fetchWithRetry(url, attempt + 1);
}
throw error;
}
}
// Internal Methods
/** Extract the `rel="next"` URL from an RFC 5988 `Link` header, if present. */
private static parseNextPageUrl(linkHeader: string | null): string | null {
if (!linkHeader) return null;
const match = HF_LINK_NEXT_REGEX.exec(linkHeader);
return match ? match[1] : null;
}
/** Full path of one shard in a split-shard GGUF set. */
private static shardPath(stem: string, index: number, total: number): string {
const pad = (n: number) => String(n).padStart(HF_SHARD_PAD_WIDTH, '0');
return `${stem}-${pad(index)}-of-${pad(total)}.gguf`;
}
/** Strip a leading YAML frontmatter block (--- ... ---) from a markdown document. */
private static stripFrontmatter(text: string): string {
const match = text.match(HF_FRONTMATTER_REGEX);
return match ? text.slice(match[0].length) : text;
}
}

Xet Storage Details

Size:
26.4 kB
·
Xet hash:
21a32453e4fc0df03b0f80d116ef6a4542e2ed7e64111395f0c211eca6d7ca9e

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.