API 参考

模型名称映射

对于所有 NPU 模型，我们使用内部名称映射，并需要填写对应的插件 ID。对于 GGUF 格式模型，它们在 CPU/GPU 上运行，无需填写模型名称。

模型名称	插件 ID	HuggingFace 仓库名
omni-neural	npu	NexaAI/OmniNeural-4B-mobile
embed-gemma	npu	NexaAI/embeddinggemma-300m-npu-mobile
parakeet	npu	NexaAI/parakeet-tdt-0.6b-v3-npu-mobile
liquid-v2	npu	NexaAI/LFM2-1.2B-npu-mobile
parakeet	npu	NexaAI/parakeet-npu-mobile
jina-rerank	npu	NexaAI/jina-v2-rerank-npu-mobile
paddleocr	npu	NexaAI/paddleocr-npu-mobile

LLM 用法

适用于文本生成与聊天应用的大语言模型。

流式对话 - NPU

支持 NEXA 格式模型的 NPU 推理。

LlmWrapper.builder()
    .llmCreateInput(
        LlmCreateInput(
            model_name = "liquid-v2",
            model_path = <your-model-folder-path>,
            config = ModelConfig(
                    max_tokens = 2048
            ),
        ),
        plugin_id = "npu"
    )
    .build()
    .onSuccess { llmWrapper = it }

val chatList = arrayListOf(ChatMessage("user", "What is AI?"))

llmWrapper.applyChatTemplate(chatList.toTypedArray(), null, false).onSuccess { template ->
    llmWrapper.generateStreamFlow(template.formattedText, GenerationConfig()).collect { result ->
        when (result) {
            is LlmStreamResult.Token -> println(result.text)
            is LlmStreamResult.Completed -> println("Done!")
            is LlmStreamResult.Error -> println("Error: ${result.throwable}")
        }
    }
}

流式对话 - CPU

支持 GGUF 格式模型的 CPU 推理。

LlmWrapper.builder()
    .llmCreateInput(
        LlmCreateInput(
            model_path = <your-model-folder-path>,
            config = ModelConfig(nCtx = 4096, max_tokens = 2048),
            plugin_id = "cpu_gpu"
        )
    )
    .build()
    .onSuccess { llmWrapper = it }
    .onFailure { error -> 
        println("Error: ${error.message}")
    }

val chatList = arrayListOf(ChatMessage("user", "What is AI?"))

llmWrapper.applyChatTemplate(chatList.toTypedArray(), null, false).onSuccess { template ->
    llmWrapper.generateStreamFlow(template.formattedText, GenerationConfig()).collect { result ->
        when (result) {
            is LlmStreamResult.Token -> println(result.text)
            is LlmStreamResult.Completed -> println("Done!")
            is LlmStreamResult.Error -> println("Error: ${result.throwable}")
        }
    }
}

多模态用法

用于图像理解与多模态应用的视觉语言模型（VLM）。

流式对话 - NPU

支持 NEXA 格式模型的 NPU 推理。

VlmWrapper.builder()
    .vlmCreateInput(
        VlmCreateInput(
            model_name = "omni-neural",  // NPU 插件的模型名称
            model_path = <your-model-folder-path>,
            config = ModelConfig(
                max_tokens = 2048,
                enable_thinking = false
            ),
            plugin_id = "npu"  // 使用 NPU 后端
        )
    )
    .build()
    .onSuccess { vlmWrapper = it }
    .onFailure { error -> 
        println("Error: ${error.message}")
    }

// 使用已加载的 VLM 进行图像 + 文本推理
val contents = listOf(
    VlmContent("image", <your-image-path>),
    VlmContent("text", <your-text>)
)

val chatList = arrayListOf(VlmChatMessage("user", contents))

vlmWrapper.applyChatTemplate(chatList.toTypedArray(), null, false).onSuccess { template ->
    val config = vlmWrapper.injectMediaPathsToConfig(chatList.toTypedArray(), GenerationConfig())
    vlmWrapper.generateStreamFlow(template.formattedText, config).collect { result ->
        when (result) {
            is LlmStreamResult.Token -> println(result.text)
            is LlmStreamResult.Completed -> println("Done!")
            is LlmStreamResult.Error -> println("Error: ${result.throwable}")
        }
    }
}

流式对话 - CPU

支持 GGUF 格式模型的 CPU 推理。

VlmWrapper.builder()
    .vlmCreateInput(
        VlmCreateInput(
            model_path = <your-model-folder-path>,
            mmproj_path = <your-mmproj-path>,  // 视觉投影权重
            config = ModelConfig(
                max_tokens = 2048,
                enable_thinking = false
            ),
            plugin_id = "cpu_gpu"
        )
    )
    .build()
    .onSuccess { vlmWrapper = it }
    .onFailure { error -> 
        println("Error: ${error.message}")
    }

// 使用已加载的 VLM 进行图像 + 文本推理
val contents = listOf(
    VlmContent("image", <your-image-path>),
    VlmContent("text", <your-text>)
)

val chatList = arrayListOf(VlmChatMessage("user", contents))

vlmWrapper.applyChatTemplate(chatList.toTypedArray(), null, false).onSuccess { template ->
    val config = vlmWrapper.injectMediaPathsToConfig(chatList.toTypedArray(), GenerationConfig())
    vlmWrapper.generateStreamFlow(template.formattedText, config).collect { result ->
        when (result) {
            is LlmStreamResult.Token -> println(result.text)
            is LlmStreamResult.Completed -> println("Done!")
            is LlmStreamResult.Error -> println("Error: ${result.throwable}")
        }
    }
}

VlmCreateInput

data class VlmCreateInput(
    val model_name: String? = null,            // 模型名称（NPU 必填）
    val model_path: String,                    // VLM 模型路径
    val tokenizer_path: String? = null,        // 可选分词器路径
    val mmproj_path: String? = null,           // 视觉投影权重（GGUF 模型）
    val config: ModelConfig,                   // 模型配置
    val plugin_id: String? = null              // "npu" 表示 NPU；"cpu_gpu" 表示 CPU/GPU；null 默认为 CPU
)

VlmChatMessage

data class VlmChatMessage(
    val role: String,                          // "system"、"user"、"assistant"
    val contents: List<VlmContent>             // 混合文本/图像/音频内容
)

VlmContent

data class VlmContent(
    val type: String,                          // "text"、"image"、"audio"
    val content: String                        // 文本或文件路径
)

嵌入用法（Embeddings）

用于语义搜索与 RAG 应用的向量嵌入。

基本用法

// 加载 NPU 推理的嵌入模型
EmbedderWrapper.builder()
    .embedderCreateInput(
        EmbedderCreateInput(
            model_name = "embed-gemma",  // NPU 插件的模型名称
            model_path = <your-model-folder-path>,
            tokenizer_path = <your-tokenizer-path>,  // 可选
            config = ModelConfig(
                max_tokens = 2048
            ),
            plugin_id = "npu",  // 使用 NPU 后端
            device_id = null    // 可选设备 ID
        )
    )
    .build()
    .onSuccess { embedderWrapper = it }
    .onFailure { error -> 
        println("Error: ${error.message}")
    }

// 为多段文本生成向量嵌入
val texts = arrayOf(<your-text1>, <your-text2>, ...)

embedderWrapper.embed(texts, EmbeddingConfig()).onSuccess { embeddings ->
    val dimension = embeddings.size / texts.size
    println("Dimension: $dimension")
    println("First 5 values: ${embeddings.take(5)}")
}

API 参考

EmbedderCreateInput

data class EmbedderCreateInput(
    val model_name: String? = null,            // NPU 模型名称
    val model_path: String,                    // 嵌入模型路径
    val tokenizer_path: String? = null,        // 分词器路径
    val config: ModelConfig,                   // 模型配置
    val plugin_id: String? = null,             // "npu" 表示 NPU；null 表示 CPU
    val device_id: String? = null              // 设备 ID（可选）
)

EmbeddingConfig

data class EmbeddingConfig(
    val normalize: Boolean = true              // 归一化嵌入（默认：true）
)

ASR 用法

用于音频转写的自动语音识别。

基本用法

// 加载 NPU 推理的 ASR 模型
AsrWrapper.builder()
    .asrCreateInput(
        AsrCreateInput(
            model_name = "parakeet",  // NPU 插件的模型名称
            model_path = <your-model-folder-path>,
            config = ModelConfig(
                max_tokens = 2048
            ),
            plugin_id = "npu"  // 使用 NPU 后端
        )
    )
    .build()
    .onSuccess { asrWrapper = it }
    .onFailure { error -> 
        println("Error: ${error.message}")
    }

// 转写音频文件
asrWrapper.transcribe(
    AsrTranscribeInput(
        audioPath = <your-audio-path>,  // 支持 .wav、.mp3 等
        language = "en",                // 语言代码："en"、"zh"、"es" 等
        timestamps = null               // 可选时间戳格式
    )
).onSuccess { result ->
    println("Transcription: ${result.result.transcript}")
}

API 参考

AsrCreateInput

data class AsrCreateInput(
    val model_name: String? = null,            // NPU 模型名称
    val model_path: String,                    // ASR 模型路径
    val config: ModelConfig,                   // 模型配置
    val plugin_id: String? = null              // "npu" 表示 NPU；null 表示 CPU
)

AsrTranscribeInput

data class AsrTranscribeInput(
    val audioPath: String,                     // 音频文件路径（.wav、.mp3 等）
    val language: String,                      // 语言代码："en"、"zh"、"es" 等
    val timestamps: String? = null             // 可选：时间戳格式
)

AsrTranscriptionResult

data class AsrTranscriptionResult(
    val result: AsrResult,                     // 转写结果
    val profileData: String                    // 性能指标
)

重排用法（Rerank）

根据查询对文档进行重排，提升检索相关性。

基本用法

// 加载 NPU 推理的重排模型
RerankerWrapper.builder()
    .rerankerCreateInput(
        RerankerCreateInput(
            model_name = "jina-rerank",  // NPU 插件的模型名称
            model_path = <your-model-folder-path>,
            tokenizer_path = <your-tokenizer-path>,  // 可选
            config = ModelConfig(
                max_tokens = 2048
            ),
            plugin_id = "npu",  // 使用 NPU 后端
            device_id = null    // 可选设备 ID
        )
    )
    .build()
    .onSuccess { rerankerWrapper = it }
    .onFailure { error -> 
        println("Error: ${error.message}")
    }

// 根据查询对文档进行重排
val query = "What is machine learning?"
val docs = arrayOf("ML is AI subset", "Weather forecast", "Deep learning tutorial")

rerankerWrapper.rerank(query, docs, RerankConfig()).onSuccess { result ->
    result.scores?.withIndex()?.sortedByDescending { it.value }?.forEach { (idx, score) ->
        println("Score: ${"%.4f".format(score)} - ${docs[idx]}")
    }
}

API 参考

RerankerCreateInput

data class RerankerCreateInput(
    val model_name: String? = null,            // NPU 模型名称
    val model_path: String,                    // 重排模型路径
    val tokenizer_path: String? = null,        // 分词器路径
    val config: ModelConfig,                   // 模型配置
    val plugin_id: String? = null,             // "npu" 表示 NPU；null 表示 CPU
    val device_id: String? = null              // 设备 ID（可选）
)

RerankConfig

data class RerankConfig(
    val topN: Int? = null                      // 仅返回前 N 个结果（null = 全部）
)

RerankerResult

data class RerankerResult(
    val scores: FloatArray,                    // 相关性分数（0.0 - 1.0）
    val scoreCount: Int,                       // 分数数量
    val profileData: String                    // 性能指标
)

方法

suspend fun rerank(query: String, documents: Array<String>, config: RerankConfig): Result<RerankerResult>
fun destroy(): Int

CV 用法

用于 OCR、目标检测与图像分类的计算机视觉模型。

基本用法

// 加载 NPU 推理的 PaddleOCR 模型
CvWrapper.builder()
    .createInput(
        CVCreateInput(
            model_name = "paddleocr",  // 模型名称
            config = CVModelConfig(
                capabilities = CVCapability.OCR,
                det_model_path = <your-det-model-folder-path>,
                rec_model_path = <your-rec-model-path>,
                char_dict_path = <your-char-dict-path>,
                qnn_model_folder_path = <your-qnn-model-folder-path>,  // 用于 NPU
                qnn_lib_folder_path = <your-qnn-lib-folder-path>       // 用于 NPU
            ),
            plugin_id = "npu"  // 使用 NPU 后端
        )
    )
    .build()
    .onSuccess { cvWrapper = it }
    .onFailure { error -> 
        println("Error: ${error.message}")
    }

// 对图像执行 OCR
cvWrapper.infer(<your-image-path>).onSuccess { results ->
    results.forEach { result ->
        println("Text: ${result.text}, Confidence: ${result.confidence}")
    }
}

API 参考

CVCreateInput

data class CVCreateInput(
    val model_name: String,                    // 模型名称："paddleocr" 等
    val config: CVModelConfig,                 // CV 模型配置
    val plugin_id: String? = null              // "npu" 表示 NPU；"cpu_gpu" 表示 CPU/GPU；null 默认为 CPU
)

CVModelConfig

data class CVModelConfig(
    val capabilities: CVCapability,            // OCR、DETECTION、CLASSIFICATION
    val det_model_path: String? = null,        // 检测模型路径
    val rec_model_path: String? = null,        // 识别模型路径
    val char_dict_path: String? = null,        // 字典文件路径
    val qnn_model_folder_path: String? = null, // QNN 模型目录（NPU）
    val qnn_lib_folder_path: String? = null    // QNN 库目录（NPU）
)

CVCapability

enum class CVCapability {
    OCR,                                       // 光学字符识别
    DETECTION,                                 // 目标检测
    CLASSIFICATION                             // 图像分类
}

CVResult

data class CVResult(
    val text: String,                          // 识别文本（OCR）
    val confidence: Float,                     // 置信度（0.0 - 1.0）
    val boundingBox: BoundingBox?,             // 边界框坐标
    val label: String?,                        // 类别标签（分类）
    val score: Float                           // 检测/分类分数
)

如何选择 CPU、GPU、NPU

在不同硬件加速模式间自由切换。

CPU/GPU 模式

// CPU/GPU 推理 - 使用 GGUF 格式模型
LlmWrapper.builder()
    .llmCreateInput(
        LlmCreateInput(
            model_path = <your-model-folder-path>,
            config = ModelConfig(max_tokens = 2048),
            plugin_id = "cpu_gpu"  // 使用 CPU/GPU 后端
        )
    )
    .build()
    .onSuccess { llmWrapper = it }
    .onFailure { error -> 
        println("Error: ${error.message}")
    }

NPU 模式（Qualcomm）

// NPU 推理 - Qualcomm Hexagon NPU，使用 NEXA 格式模型
LlmWrapper.builder()
    .llmCreateInput(
        LlmCreateInput(
            model_name = "liquid-v2",  // NPU 必填的模型名称
            model_path = <your-model-folder-path>,
            config = ModelConfig(
                max_tokens = 2048,
                npu_lib_folder_path = applicationInfo.nativeLibraryDir,
                npu_model_folder_path = <your-npu-model-folder-path>
            ),
            plugin_id = "npu"  // 使用 NPU 后端
        )
    )
    .build()
    .onSuccess { llmWrapper = it }
    .onFailure { error -> 
        println("Error: ${error.message}")
    }

需要帮助？

加入我们的社区获取支持、分享项目并与其他开发者交流。

Discord 社区

获取实时支持并与 Nexa AI 社区交流

Slack 社区

与开发者协作并访问社区资源

Was this page helpful?

Yes

快速开始

Nexa CLI 使用

Android SDK

Linux Docker

Python 库

iOS & macOS SDK

社区

​模型名称映射

​LLM 用法

​流式对话 - NPU

​流式对话 - CPU

​多模态用法

​流式对话 - NPU

​流式对话 - CPU

​API 参考

​VlmCreateInput

​VlmChatMessage

​VlmContent

​嵌入用法（Embeddings）

​基本用法

​API 参考

​EmbedderCreateInput

​EmbeddingConfig

​ASR 用法

​基本用法

​API 参考

​AsrCreateInput

​AsrTranscribeInput

​AsrTranscriptionResult

​重排用法（Rerank）

​基本用法

​API 参考

​RerankerCreateInput

​RerankConfig

​RerankerResult

​方法

​CV 用法

​基本用法

​API 参考

​CVCreateInput

​CVModelConfig

​CVCapability

​CVResult

​如何选择 CPU、GPU、NPU

​CPU/GPU 模式

​NPU 模式（Qualcomm）

​需要帮助？

Discord 社区

Slack 社区

模型名称映射

LLM 用法

流式对话 - NPU

流式对话 - CPU

多模态用法

流式对话 - NPU

流式对话 - CPU

API 参考

VlmCreateInput

VlmChatMessage

VlmContent

嵌入用法（Embeddings）

基本用法

API 参考

EmbedderCreateInput

EmbeddingConfig

ASR 用法

基本用法

API 参考

AsrCreateInput

AsrTranscribeInput

AsrTranscriptionResult

重排用法（Rerank）

基本用法

API 参考

RerankerCreateInput

RerankConfig

RerankerResult

方法

CV 用法

基本用法

API 参考

CVCreateInput

CVModelConfig

CVCapability

CVResult

如何选择 CPU、GPU、NPU

CPU/GPU 模式

NPU 模式（Qualcomm）

需要帮助？