快速开始
如果尚未拉取模型，请先拉取。例如，拉取 Qwen3：
nexa pull NexaAI/Qwen3-0.6B-GGUF
http://127.0.0.1:18181。
保持该终端窗口运行服务器，并在另一个终端窗口中发送请求。
查看可配置的服务器选项：nexa serve -h
你也可以直接体验服务端交互：
nexa run NexaAI/Qwen3-0.6B-GGUF
nexa pull 拉取的任意模型。run 命令会启动一个与 nexa infer 类似的 REPL 对话界面，但所有对话由本地 nexa serve 服务处理。
模型选择
部分模型仅能在特定平台运行。例如，MLX 模型仅能在 macOS 13+ 设备运行；OmniNeural 仅能在搭载 Qualcomm NPU 的笔记本上运行。下表给出了各系统的示例模型，便于你快速尝试：
| 操作系统 | 模态 | 推荐模型 |
|---|
| macOS | LLM | NexaAI/gpt-oss-20b-MLX-4bit |
| macOS | VLM | NexaAI/gemma-3n-E4B-it-4bit-MLX |
| macOS | 图像生成 | NexaAI/sdxl-turbo |
| macOS | ASR | NexaAI/whisper-large-v3-turbo-MLX |
| macOS | TTS | NexaAI/Kokoro-82M-bf16-MLX |
| Windows x86 | LLM | NexaAI/Qwen3-4B-GGUF |
| Windows x86 | VLM | NexaAI/gemma-3n |
| Windows x86 | 图像生成 | NexaAI/Prefect-illustrious-XL-v2.0p |
| Windows Qualcomm ARM64 | LLM | NexaAI/Qwen3-4B-npu |
| Windows Qualcomm ARM64 | VLM | NexaAI/OmniNeural-4B |
| Windows Qualcomm ARM64 | ASR | NexaAI/parakeet-tdt-0.6b-v3-npu |
| Windows AMD NPU | 图像生成 | NexaAI/sdxl-turbo-amd-npu |
| Windows Intel NPU | LLM | NexaAI/llama-3.1-8B-intel-npu |
/v1/chat/completions
为给定会话生成模型回复。支持 LLM（仅文本） 与 VLM（图像+文本）。
使用 LLM
请求体示例
{
"model": "NexaAI/Qwen3-0.6B-GGUF",
"messages": [
{"role": "user", "content": "Hello! Briefly introduce yourself."}
],
"max_tokens": 256,
"temperature": 0.7,
"stream": false
}
使用示例
curl -X POST http://127.0.0.1:18181/v1/chat/completions -H "Content-Type: application/json" -d "{\"model\": \"NexaAI/Qwen3-0.6B-GGUF\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}], \"max_tokens\": 64}"
使用 VLM
请求体示例
image_url 可以是以下几种类型之一：
- 远程 URL，例如：
https://example.com/photo.jpg
- base64 编码的字符串，例如：
data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
- 服务器上的本地文件路径，服务器需要有对此文件的访问权限。例如：
file:///C:/Users/Username/Pictures/photo.jpg（Windows）或 file:///Users/Username/Pictures/photo.jpg（MacOS/Linux），file:// 可以省略，直接提供路径，如 C:/Users/Username/Pictures/photo.jpg 或 /Users/Username/Pictures/photo.jpg。
{
"model": "NexaAI/qwen3vl-GGUF",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "Describe this image succinctly."},
{"type": "image_url", "image_url": {"url": "</path/to/image>"}}
]
}
]
}
使用示例
curl -X POST http://127.0.0.1:18181/v1/chat/completions -H "Content-Type: application/json" -d "{\"model\": \"NexaAI/qwen3vl-GGUF\", \"messages\": [{\"role\": \"user\", \"content\": [{\"type\": \"text\", \"text\": \"what is main color of the picture\"}, {\"type\": \"image_url\", \"image_url\": {\"url\": \"</path/to/image>\"}}]}], \"stream\": false}"
/v1/images/generations
根据提示词生成图像。
以下示例使用 NexaAI/Prefect-illustrious-XL-v2.0p-fp16-cuda，该模型适用于绝大多数 CUDA（NVIDIA GPU）环境。如果你在 Apple Silicon 上运行，请使用 MLX 兼容的模型（例如 nexaml/sdxl-turbo-ryzen-ai）。请确保所选模型与硬件能力匹配。
请求体示例
{
"model": "NexaAI/Prefect-illustrious-XL-v2.0p-fp16-cuda",
"prompt": "A white cat with blue eyes",
"n": 1,
"size": "512x512",
"response_format": "url"
}
使用示例
curl -X POST http://127.0.0.1:18181/v1/images/generations -H "Content-Type: application/json" -d "{\"model\":\"NexaAI/Prefect-illustrious-XL-v2.0p-fp16-cuda\",\"prompt\":\"A white cat with blue eyes\",\"n\":1,\"size\":\"512x512\",\"response_format\":\"url\"}"
/v1/embeddings
为输入文本创建向量嵌入。可用于将文本（或文档分块）转换为向量并建立检索索引。
当你需要将 文本或文档分块转换为向量 以用于检索系统时，请使用该接口。确保所选模型支持 embeddings（向量嵌入）（例如 djuna/jina-embeddings-*）。如果使用非嵌入模型调用该 API 会返回错误。
最小请求体
{
"model": "djuna/jina-embeddings-v2-small-en-Q5_K_M-GGUF",
"input": "Hello, world!"
}
使用示例
curl -X POST http://127.0.0.1:18181/v1/embeddings -H "Content-Type: application/json" -d "{\"model\":\"djuna/jina-embeddings-v2-small-en-Q5_K_M-GGUF\",\"input\":\"Hello, world!\"}"
/v1/reranking
根据查询对文档进行重排，返回与输入顺序对应的一组相关性分数（值越高表示越相关）。
在完成 粗检索（如嵌入向量 Top-K）后，使用该接口提升最终排序质量。请确保所选模型支持重排（reranking）。如果使用非重排模型调用该 API 会返回错误。
最小请求体
{
"model": "NexaAI/jina-v2-rerank-npu",
"query": "What is machine learning?",
"documents": [
"Machine learning is a subset of artificial intelligence.",
"Machine learning algorithms learn patterns from data.",
"The weather is sunny today.",
"Deep learning is a type of machine learning."
],
"batch_size": 4,
"normalize": true,
"normalize_method": "softmax"
}
使用示例
curl -X POST http://127.0.0.1:18181/v1/reranking -H "Content-Type: application/json" -d "{\"model\":\"NexaAI/jina-v2-rerank-npu\",\"query\":\"What is machine learning?\",\"documents\":[\"Machine learning is a subset of artificial intelligence.\",\"Machine learning algorithms learn patterns from data.\",\"The weather is sunny today.\",\"Deep learning is a type of machine learning.\"],\"batch_size\":4,\"normalize\":true,\"normalize_method\":\"softmax\"}"
