initialize static method

Future<void> initialize({
  1. String? tokenizerAsset,
  2. String? modelAsset,
  3. RagModelPack? modelPack,
  4. String? tokenizerPath,
  5. String? modelPath,
  6. String? databaseName,
  7. int maxChunkChars = kDefaultMaxChunkChars,
  8. int overlapChars = kDefaultOverlapChars,
  9. int? embeddingIntraOpNumThreads,
  10. ThreadUseLevel? threadLevel,
  11. bool deferIndexWarmup = false,
  12. double defaultVectorWeight = kDefaultVectorWeight,
  13. double defaultBm25Weight = kDefaultBm25Weight,
  14. void onProgress(
    1. String status
    )?,
})

Initialize the RAG engine. Call once in main().

This will:

  1. Initialize the Rust library (FFI)
  2. Load the tokenizer from assets
  3. Load the ONNX embedding model
  4. 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 of tokenizerAsset/modelAsset
  • tokenizerPath, 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 until reembedAll() or clearAndRestart().
  • 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., 1 for minimal CPU). Mutually exclusive with threadLevel.
  • threadLevel - High-level thread usage: low (~20%), medium (~40%), high (~80%). Mutually exclusive with embeddingIntraOpNumThreads.
  • 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 and RagSearchTool.fromMobileRag) when a call does not pass vectorWeight / 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.md lists 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 apps
  • embeddingIntraOpNumThreads: 2 - Fine-grained control

⚠️ If both are set:

  • Debug builds: throws an AssertionError
  • Release builds: threadLevel takes 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;
  }
}