initialize static method
Future<void>
initialize({
- String? tokenizerAsset,
- String? modelAsset,
- RagModelPack? modelPack,
- String? tokenizerPath,
- String? modelPath,
- String? databaseName,
- int maxChunkChars = kDefaultMaxChunkChars,
- int overlapChars = kDefaultOverlapChars,
- int? embeddingIntraOpNumThreads,
- ThreadUseLevel? threadLevel,
- bool deferIndexWarmup = false,
- double defaultVectorWeight = kDefaultVectorWeight,
- double defaultBm25Weight = kDefaultBm25Weight,
- void onProgress(
- String status
Initialize the RAG engine. Call once in main().
This will:
- Initialize the Rust library (FFI)
- Load the tokenizer from assets
- Load the ONNX embedding model
- Initialize the SQLite database
Parameters:
tokenizerAsset- Path to tokenizer.json in assets (e.g.,'assets/tokenizer.json')modelAsset- Path to ONNX model file in assets (e.g.,'assets/model.onnx')modelPack- A verified Model Pack (RagModelPack.asset) instead oftokenizerAsset/modelAssettokenizerPath,modelPath- Files your app already placed on disk, for example a model downloaded on first launch so it is not in the app bundle. They are loaded where they are, without an asset copy. Pass both, and none of the asset or Model Pack options. The embedding fingerprint includes the model's file name and a hash of the file, so any change to either locks search untilreembedAll()orclearAndRestart().databaseName- SQLite database file name (default:'rag.sqlite')maxChunkChars- Maximum characters per chunk (default:kDefaultMaxChunkChars)overlapChars- Overlap between chunks for context continuity (default:kDefaultOverlapChars)embeddingIntraOpNumThreads- Precise thread count for ONNX (e.g.,1for minimal CPU). Mutually exclusive withthreadLevel.threadLevel- High-level thread usage:low(~20%),medium(~40%),high(~80%). Mutually exclusive withembeddingIntraOpNumThreads.deferIndexWarmup- If true, returns before BM25/HNSW warmup completes. Use isIndexReady or warmupFuture to gate search quality.defaultVectorWeight,defaultBm25Weight- Weights for hybrid search (searchHybrid, searchHybridWithContext, searchMeta, ask, prepareAsk, CollectionRag andRagSearchTool.fromMobileRag) when a call does not passvectorWeight/bm25Weight. Default 0.2 / 0.8, which suits the English-only default model. With a multilingual model such as KoEn-E5-Tiny, more vector weight finds answers that share few words with the question;docs/guides/model_setup.mdlists what each weight found with KoEn-E5-Tiny. Each must be between 0.0 and 1.0, and not both 0.0.onProgress- Callback for initialization progress updates
Thread Configuration:
Choose ONE of the following:
threadLevel: ThreadUseLevel.medium- Simple, recommended for most appsembeddingIntraOpNumThreads: 2- Fine-grained control
⚠️ If both are set:
- Debug builds: throws an AssertionError
- Release builds:
threadLeveltakes precedence and a warning is logged
Example:
await MobileRag.initialize(
tokenizerAsset: 'assets/tokenizer.json',
modelAsset: 'assets/model.onnx',
threadLevel: ThreadUseLevel.medium, // Recommended
onProgress: (status) => print(status),
);
Implementation
static Future<void> initialize({
String? tokenizerAsset,
String? modelAsset,
RagModelPack? modelPack,
String? tokenizerPath,
String? modelPath,
String? databaseName,
int maxChunkChars = kDefaultMaxChunkChars,
int overlapChars = kDefaultOverlapChars,
int? embeddingIntraOpNumThreads,
ThreadUseLevel? threadLevel,
bool deferIndexWarmup = false,
double defaultVectorWeight = kDefaultVectorWeight,
double defaultBm25Weight = kDefaultBm25Weight,
void Function(String status)? onProgress,
}) async {
if (_instance != null) {
onProgress?.call('Already initialized');
return;
}
final running = _initializing;
if (running != null) {
// Same as calling after it finished: the first call's options win.
onProgress?.call('Already initializing');
return running;
}
final initializing = _initialize(
tokenizerAsset: tokenizerAsset,
modelAsset: modelAsset,
modelPack: modelPack,
tokenizerPath: tokenizerPath,
modelPath: modelPath,
databaseName: databaseName,
maxChunkChars: maxChunkChars,
overlapChars: overlapChars,
embeddingIntraOpNumThreads: embeddingIntraOpNumThreads,
threadLevel: threadLevel,
deferIndexWarmup: deferIndexWarmup,
defaultVectorWeight: defaultVectorWeight,
defaultBm25Weight: defaultBm25Weight,
onProgress: onProgress,
);
_initializing = initializing;
try {
await initializing;
} finally {
if (identical(_initializing, initializing)) _initializing = null;
}
}