Documentation – Engine parameters

Net: ModelCachePath

Fri, 24 Apr 2026 00:00:00 +0000

ModelCachePath is the folder where the engine stores downloaded model files. First-run downloads from Hugging Face (or the Aspose catalog) land here; subsequent runs load from this cache.

Quick reference


Type	`string?`
Default	`<LocalAppData>/Aspose.LLM/models`
Category	Engine
Field on	`EngineParameters.ModelCachePath`

What it does

On Windows: %LOCALAPPDATA%\Aspose.LLM\models.
On Linux / macOS: the equivalent Environment.SpecialFolder.LocalApplicationData path, joined with Aspose.LLM/models.
Overriding sets a custom directory.

At each AsposeLLMApi.Create, the engine checks this folder for the preset’s model file. If present, load. If absent, download from the resolved source (BaseModelSourceParameters), save into this folder, and load.

When to change it

Scenario	Value
Default	`null` or unset
Shared cache across multiple applications	`/srv/aspose-llm/models` (or equivalent)
Faster storage (SSD when `LocalAppData` is on HDD)	Path to SSD folder
Docker / container with mounted volume	`/models` (volume mount)
Pre-populated offline deployment	Path to the pre-populated cache

Example

var preset = new Qwen25Preset();
preset.EngineParameters.ModelCachePath = @"D:\models";
// Large models will land on drive D instead of C.

using var api = AsposeLLMApi.Create(preset);

Container pattern:

preset.EngineParameters.ModelCachePath = "/models";  // Docker volume mount

Interactions

BaseModelSourceParameters — resolution order; the cached file must match the requested source.
BinaryManagerParameters.BinaryPath — separate cache for native binaries; different folder.

What’s next

Offline deployment use case — pre-populating the cache.
Model source parameters — what gets cached.
Engine parameters hub — all engine knobs.

Net: EnableDebugLogging

Fri, 24 Apr 2026 00:00:00 +0000

EnableDebugLogging toggles verbose diagnostic logs from the native llama.cpp layer. Off by default to minimize production overhead; flip on when investigating a specific problem.

Quick reference


Type	`bool`
Default	`false`
Category	Engine
Field on	`EngineParameters.EnableDebugLogging`

What it does

false (default) — the native layer produces no diagnostic output. Inference runs at full throughput.
true — the native layer emits tagged lines ([MM], [CTX], [KV], etc.) via NativeLoggerAdapter into the ILogger you pass to AsposeLLMApi.Create. Lines are also written to the file at LogDirectoryPath.

Debug logging adds measurable overhead — typically 5-15 % throughput loss. Not intended for production.

When to change it

Scenario	Value
Default production	`false`
Diagnosing template mismatch, KV eviction, vision alignment	`true`
Benchmarking a specific backend	`false` (avoid logging overhead)
CI / staging runs	Either — depends on debugging requirements

Example

using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(b =>
    b.AddConsole().SetMinimumLevel(LogLevel.Debug));
var logger = loggerFactory.CreateLogger<Program>();

var preset = new Qwen25Preset();
preset.EngineParameters.EnableDebugLogging = true;
preset.EngineParameters.LogDirectoryPath = "logs/debug-run.log";

using var api = AsposeLLMApi.Create(preset, logger);
// Tagged [MM], [CTX], [KV] lines flow to both the logger and the file.

Interactions

LogDirectoryPath — file destination for debug output.
MultimodalContextParameters.Verbosity — mtmd-layer verbosity, independent of this flag.
ILogger passed to AsposeLLMApi.Create — debug lines route through it.

What’s next

Logging and diagnostics — tagged log taxonomy.
Debugging vision — multimodal-specific diagnosis.
Engine parameters hub — all engine knobs.

Net: LogDirectoryPath

Fri, 24 Apr 2026 00:00:00 +0000

LogDirectoryPath is the file path where the native logger writes output. Despite the name, the value is a full file path — not a directory.

Quick reference


Type	`string`
Default	`"logs/log.txt"`
Category	Engine
Field on	`EngineParameters.LogDirectoryPath`

What it does

When the native logger writes (mostly when EnableDebugLogging is true), output goes to this file. If the file does not exist, it is created; if it does, output is appended.

Default logs/log.txt — a file log.txt inside a logs folder, resolved relative to the current working directory.
Absolute path — write to a specific location regardless of working directory.

When to change it

Scenario	Value
Default	`"logs/log.txt"`
Per-environment log file	`"logs/staging.log"`, `"logs/prod.log"`
Centralized logging location	`"/var/log/aspose-llm/app.log"`
Working directory is not writable	Absolute path to a writable folder

Example

var preset = new Qwen25Preset();
preset.EngineParameters.EnableDebugLogging = true;
preset.EngineParameters.LogDirectoryPath = "/var/log/aspose-llm/app.log";

using var api = AsposeLLMApi.Create(preset, logger);

Ensure the parent directory exists and the process has write permission:

var logFile = "/var/log/aspose-llm/app.log";
Directory.CreateDirectory(Path.GetDirectoryName(logFile)!);
preset.EngineParameters.LogDirectoryPath = logFile;

Interactions

EnableDebugLogging — the main switch for output that this file receives.
ILogger passed to AsposeLLMApi.Create — complementary managed-side logging.

What’s next

Logging and diagnostics — full logging reference.
Engine parameters hub — all engine knobs.

Net: DefaultThreads

Fri, 24 Apr 2026 00:00:00 +0000

DefaultThreads is the thread count the engine uses when the more specific ContextParameters.NThreads and NThreadsBatch are not set.

Quick reference


Type	`int`
Default	`Environment.ProcessorCount - 1`
Category	Engine
Field on	`EngineParameters.DefaultThreads`

What it does

When ContextParameters.NThreads is null, the engine falls back to DefaultThreads. Same for NThreadsBatch.

The default leaves one logical core free for the rest of your application. On an 8-core machine, the default is 7. On a 16-core machine, 15.

When to change it

Scenario	Value
Default	unset (uses `ProcessorCount - 1`)
Dedicated inference box	`Environment.ProcessorCount` (all cores)
CPU-quota-limited container	Fixed smaller number matching quota
Shared host with other heavy work	Half `ProcessorCount`

For per-phase control (generation vs prompt processing), set NThreads and NThreadsBatch directly — they override DefaultThreads.

Example

var preset = new Qwen25Preset();
preset.EngineParameters.DefaultThreads = 4;
// Only 4 threads used when ContextParameters.NThreads is null.

using var api = AsposeLLMApi.Create(preset);

Interactions

ContextParameters.NThreads — generation threads; overrides default when set.
ContextParameters.NThreadsBatch — prompt-processing threads; overrides default when set.

What’s next

NThreads — per-phase override.
CPU acceleration — threading strategy.
Engine parameters hub — all engine knobs.