docs: add FAQ, document in-memory model loading; bump version to 0.8.0

Cargo.toml

@@ -3,7 +3,7 @@ members = [".", "oar-ocr-derive", "oar-ocr-core", "oar-ocr-vl"]
 resolver = "2"
 
 [workspace.package]
-version = "0.7.5"
+version = "0.8.0"
 edition = "2024"
 rust-version = "1.95"
 license = "Apache-2.0"
@@ -12,8 +12,8 @@ repository = "https://github.com/greatv/oar-ocr"
 homepage = "https://github.com/greatv/oar-ocr"
 
 [workspace.dependencies]
-oar-ocr-core = { version = "0.7.5", path = "oar-ocr-core", default-features = false }
-oar-ocr-derive = { version = "0.7.5", path = "oar-ocr-derive", default-features = false }
+oar-ocr-core = { version = "0.8.0", path = "oar-ocr-core", default-features = false }
+oar-ocr-derive = { version = "0.8.0", path = "oar-ocr-derive", default-features = false }
 
 # Shared third-party dependencies (kept in sync via workspace inheritance).
 clap = { version = "4.5.42", features = ["derive"] }

README.md

@@ -29,6 +29,8 @@ cargo add oar-ocr --features auto-download
 
 Bare file names passed to the builders are then fetched from [ModelScope](https://www.modelscope.cn/models/greatv/oar-ocr) into `$OAR_HOME` (default `~/.oar`) and verified against their expected SHA-256. See [docs/models.md](docs/models.md#auto-download-via-the-auto-download-feature) for the exact path resolution rules.
 
+Everywhere a builder accepts a model path it also accepts raw ONNX bytes (e.g. `include_bytes!`), so models can be embedded into a single binary — see [Loading Models from Memory](docs/usage.md#loading-models-from-memory).
+
 ### Basic Usage
 
 ```rust
@@ -143,6 +145,7 @@ For advanced document understanding using Vision-Language Models (like PaddleOCR
 - [**Usage Guide**](docs/usage.md) - Detailed API usage, builder patterns, GPU configuration
 - [**Pre-trained Models**](docs/models.md) - Model download links and recommended configurations
 - [**Environment Variables**](docs/environment-variables.md) - Runtime configuration via `OAR_*` variables
+- [**FAQ**](docs/FAQ.md) - Common build and runtime questions
 
 ## Examples
 

docs/FAQ.md

@@ -0,0 +1,49 @@
+# Frequently Asked Questions
+
+Common build and runtime questions, distilled from GitHub issues.
+
+## Windows: linking fails with `LNK2001: unresolved external symbol __std_find_trivial_8`
+
+Unresolved `__std_*` symbols (`__std_find_trivial_*`, `__std_max_element_*`,
+`__std_search_*`, ...) mean the linker's MSVC STL is too old. The prebuilt
+ONNX Runtime binaries that `ort-sys` downloads are compiled with Visual
+Studio 2022 (MSVC v143) and reference vectorized STL helpers that do not
+exist in the VS 2019 (v142) link libraries.
+
+Fix:
+
+1. Install **Visual Studio 2022** or **Build Tools for Visual Studio 2022**
+   with the "Desktop development with C++" workload (MSVC v143 + Windows SDK).
+2. Run `cargo clean` and rebuild — rustc picks the newest installed MSVC
+   toolset automatically.
+
+VS 2019 and VS 2022 build tools can coexist; only the newer one needs to be
+present for linking. (See issue [#105](https://github.com/GreatV/oar-ocr/issues/105).)
+
+## GPU inference is slower than CPU for PP-OCRv6 tiny/small
+
+Expected. The tiny/small models are so small that per-call overhead —
+host↔device tensor copies, kernel launches, CPU/GPU synchronization, plus
+pre/post-processing that always runs on the CPU — outweighs the compute the
+GPU saves. Measured on an RTX 4090 + i9-13900KF (single image, warmup
+excluded):
+
+| Model  | CPU        | GPU (CUDA EP)             |
+| ------ | ---------- | ------------------------- |
+| tiny   | 34 ms/img  | 44 ms/img                 |
+| small  | 59 ms/img  | 77 ms/img                 |
+| medium | 404 ms/img | **173 ms/img** (2.3× faster) |
+
+Guidelines:
+
+- For tiny/small, use the default CPU mode (the `simd` feature is on by default).
+- Use the medium model, or batch several images per `predict()` call, when
+  GPU acceleration matters.
+- Exclude the first call when benchmarking: it includes cuDNN initialization
+  and algorithm selection (~5× slower than steady state).
+
+Also note that requesting `OrtExecutionProvider::CUDA` without building with
+`--features cuda` makes the pipeline builder return an error — check the
+`Result` of `.build()`. Without the `cuda` feature, the downloaded ONNX
+Runtime is CPU-only and the GPU is never used.
+(See issue [#151](https://github.com/GreatV/oar-ocr/issues/151).)

docs/models.md

@@ -198,6 +198,10 @@ When the feature is enabled, registered file names are fetched from [`greatv/oar
 
 ### Path resolution rules
 
+These rules apply to *path* sources only; models passed as in-memory bytes
+(see [Loading Models from Memory](usage.md#loading-models-from-memory)) bypass
+path resolution entirely.
+
 For each model path argument the builder applies these checks in order:
 
 1. **Existing file wins.** If the path refers to a real file on disk it is used as-is — no registry lookup, no hash check, no network. A `./pp-ocrv5_mobile_det.onnx` next to the binary always shadows the registry.

src/lib.rs

@@ -7,6 +7,7 @@
 //!
 //! - Complete OCR pipeline from image to text
 //! - High-level builder APIs for easy pipeline configuration
+//! - Models load from file paths or in-memory bytes (`include_bytes!`)
 //! - Model adapter system for easy model swapping
 //! - Batch processing support
 //! - ONNX Runtime integration for fast inference