本地服务器 - Nexa Sdk

import Feedback from "/snippets/page-feedback.mdx";

GenieX 内置推理服务器，提供兼容 OpenAI 协议的 API。在设备端运行模型，并连接到任意支持 OpenAI 协议的应用或框架——例如 LangChain 等智能体框架、OpenClaw 等 AI 原生应用，或你自己的代码。无需云端依赖。

前置条件

已安装 CLI——详见安装。
容器内交互式 shell（仅 Docker）——详见交互式运行。
已拉取模型。geniex serve 不会自动下载模型。

启动服务器

拉取模型：

bash

geniex pull ai-hub-models/Qwen3-4B-Instruct-2507

启动服务器：

bash

geniex serve

服务器默认运行在 http://127.0.0.1:18181。保持该终端开启，并在另一个终端中发送请求。运行 geniex serve -h 查看所有可配置选项。

POST /v1/chat/completions

为给定对话创建模型响应。支持 LLM（纯文本）与 VLM（图像 + 文本）。

LLM 请求

json

{
  "model": "ai-hub-models/Qwen3-4B-Instruct-2507",
  "messages": [
    {"role": "user", "content": "Hello! Briefly introduce yourself."}
  ],
  "max_tokens": 256,
  "temperature": 0.7,
  "stream": false
}

通过 Swagger UI 试用

在浏览器中打开 http://127.0.0.1:18181 即可访问内置的 Swagger UI。

步骤 1. 展开 POST /v1/chat/completions 端点，查看示例请求体与 schema。

步骤 2. 点击 Try it out，根据需要编辑请求体，然后点击 Execute。

步骤 3. 查看响应——200 状态码以及模型生成的回复。

VLM 请求

image_url.url 支持三种格式：

格式	示例
本地文件路径（`file://` 前缀可选）	`C:/Users/Username/Pictures/photo.jpg`、`file:///tmp/photo.jpg`
HTTP / HTTPS URL——由服务器拉取	`https://example.com/image.jpg`
Base64 data URL——内联图像字节	`data:image/png;base64,iVBORw0KGgo...`

<Note> **在 Docker 中运行？** 本地路径会在**容器内**解析，而不是主机。安装命令已经把 `$PWD/data` 挂载到 `/data`——把图片放进去，然后传 `/data/cat.jpg` 即可。或者直接用 HTTP URL 或 base64 data URL，绕过文件系统。 </Note>

json

{
  "model": "ai-hub-models/Qwen2.5-VL-7B-Instruct",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image succinctly."},
        {"type": "image_url", "image_url": {"url": "</path/to/image>"}}
      ]
    }
  ]
}

在 Swagger UI 中将请求体替换为上述 VLM payload，把 image_url.url 指向本地图片，然后点击 Execute。

Python 客户端（OpenAI SDK）

由于服务器使用 OpenAI 协议，可直接将官方 openai Python 客户端指向本地端点，复用任意已有的 OpenAI 代码。先通过 pip install openai 安装，然后创建 client：

python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:18181/v1",
    api_key="geniex",  # any non-empty string; the server does not check it
)

下面的示例都复用此 client。请把 model 替换为已拉取的模型；可选的 :<precision> 后缀（例如 Q4_0、Q4_K_M、Q8_0）选择量化变体——Q4_0 推荐用于 Hexagon NPU 上的 llama.cpp。详见支持的精度（量化）。

流式（Streaming）

按 delta 到达顺序逐段打印：

python

stream = client.chat.completions.create(
    model="unsloth/Qwen3-4B-GGUF:Q4_0",
    messages=[
        {"role": "user", "content": "Hello! Briefly introduce yourself."},
    ],
    max_tokens=256,
    temperature=0.7,
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
print()

Chat completion（非流式）

单次请求、单次响应，不启用流式——标准的 OpenAI chat.completions.create 形式。enable_think=False 关闭 Qwen3 默认的 <think>…</think> 推理前缀，让回复内容更干净。

python

resp = client.chat.completions.create(
    model="unsloth/Qwen3-4B-GGUF:Q4_0",
    messages=[
        {"role": "user", "content": "Hello! Briefly introduce yourself."},
    ],
    max_tokens=128,
    temperature=0.7,
    extra_body={"enable_think": False},
)

print(resp.choices[0].message.content)
print("finish_reason:", resp.choices[0].finish_reason)
print("usage:", resp.usage)

输出：

text

Hello! I'm Qwen, a large language model developed by Alibaba Cloud. I can help with a wide range of tasks, including answering questions, writing articles, creating stories, and more. I'm here to assist you in any way I can! How can I help you today?
finish_reason: stop
usage: CompletionUsage(completion_tokens=58, prompt_tokens=19, total_tokens=77, ...)

工具调用（Tool calling）

函数/工具调用使用标准的 OpenAI tools schema。服务器会从模型生成的文本中解析工具调用（<tool_call>…</tool_call> 标签或 ```json 代码块——例如 Qwen3 的 chat template 产出的格式），并以 OpenAI tool_calls 形式返回。

<Note> 每次助手响应仅解析一个工具调用——暂不支持单次响应中的并行工具调用。 </Note>

两步往返：(1) 模型返回一条 tool_calls 消息；(2) 本地执行工具，将结果作为 role="tool" 消息回传给模型，模型基于结果生成最终答案。

python

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather in a given city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name, e.g. Beijing"},
                },
                "required": ["city"],
            },
        },
    }
]

def get_weather(city: str) -> dict:
    # replace this with your real implementation
    return {"city": city, "temperature_c": 24, "condition": "Sunny"}

messages = [
    {"role": "user", "content": "What is the weather in Beijing? Use the tool."},
]

# Step 1 — model requests a tool call.
first = client.chat.completions.create(
    model="unsloth/Qwen3-4B-GGUF:Q4_0",
    messages=messages,
    tools=tools,
    tool_choice="auto",
    max_tokens=256,
    extra_body={"enable_think": False},
)
call = first.choices[0].message.tool_calls[0]
print("finish_reason:", first.choices[0].finish_reason)  # -> "tool_calls"
print("call:", call.function.name, call.function.arguments)

# Step 2 — run the tool, feed the result back.
result = get_weather(**json.loads(call.function.arguments))

messages.append(first.choices[0].message)
messages.append(
    {
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps(result),
    }
)

final = client.chat.completions.create(
    model="unsloth/Qwen3-4B-GGUF:Q4_0",
    messages=messages,
    tools=tools,
    max_tokens=128,
    extra_body={"enable_think": False},
)
print(final.choices[0].message.content)

输出：

text

finish_reason: tool_calls
call: get_weather {"city": "Beijing"}
The weather in Beijing is 24°C and sunny.

其他端点

GET /v1/models——列出可用模型。
GET /v1/models/{model}——查询指定模型的信息。