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

前置条件

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

启动服务器

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

POST /v1/chat/completions

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

LLM 请求

Example Value

分离推理内容(reasoning_content)

思考模型默认会把思维链放入 message.reasoning_content,让 content 只保留最终回复。如需把原始推理保留在 message.content 中,可在 /v1/chat/completions 请求体中将 reasoning_format 设为 none:
deepseek 是默认值;deepseek、deepseek-legacy 和 auto 会分离推理内容,none 则保留内联推理。此设置不会关闭模型的推理(与 enable_think: false 不同),流式响应和工具调用请求也适用。使用 OpenAI SDK 读取分离字段的方式见 Python client 示例。

通过 Swagger UI 试用

在浏览器中打开 http://127.0.0.1:18181 即可访问内置的 Swagger UI。 步骤 1. 展开 POST /v1/chat/completions 端点,查看示例请求体与 schema。 Swagger UI 展示 chat completions 端点及示例请求体 步骤 2. 点击 Try it out,根据需要编辑请求体,然后点击 Execute。 在 Try-it-out 模式下编辑请求体后执行 步骤 3. 查看响应——200 状态码以及模型生成的回复。 响应体展示 200 成功响应及模型回复

VLM 请求

image_url.url 支持三种格式:
在 Docker 中运行? 本地路径会在容器内解析,而不是主机。安装命令已经把 $PWD/data 挂载到 /data——把图片放进去,然后传 /data/cat.jpg 即可。或者直接用 HTTP URL 或 base64 data URL,绕过文件系统。
Example Value
在 Swagger UI 中将请求体替换为上述 VLM payload,把 image_url.url 指向本地图片,然后点击 Execute。 在 Try-it-out 模式下编辑 VLM 请求体后执行 响应体展示 200 成功响应及 VLM 对图像的描述

POST /v1/completions

对 prompt 生成原始续写,不套用聊天模板 —— 提示词会原样传给模型。适用于自行构造完整提示词的客户端,例如编辑器的 fill-in-the-middle(FIM)代码补全:把模型的 FIM 标记直接写进 prompt。仅支持 LLM 模型。
Example Value
响应中的 choices[0].text 即原始补全内容,可直接插入光标处。stream、stop、echo 及采样参数(temperature、top_p、top_k、min_p、repetition_penalty、seed)与 /v1/chat/completions 行为一致;不支持 suffix —— 请改用模型的 FIM 标记把后缀编码进 prompt。

POST /v1/decisions

使用已导入 GenieX 缓存的 llama_cpp LLM 或 VLM,按顺序评估 predicate、choice 和 score 问题。此端点采用 OpenAI Decisions 的请求与响应结构。带有 systemone 的模型使用对应的 OpenJEV、LEV 或 Nimble 决策路径及模型 temperature;缺少 decision.type 时默认按 OpenJEV 处理。没有 systemone 时使用常规 chat template 和通用选项 prompt,temperature 回退到 1.0。LEV 的 choice 会平均两种选项顺序,predicate 使用九档评分;LLM 和 VLM 均通过原生 logits 评分(LEV 模型本身仅支持文本)。VLM 还可评估内联图像和音频。
input 可以是非空文本字符串,也可以是包含 input_text、input_image 和 GenieX 扩展 input_audio 部分的 user message 数组。图像(image_url)和音频(input_audio.data)复用 chat 端点的 SaveURIToTempFile 路径,支持本地路径、file://、HTTP(S) 及 data URL。音频也与 chat 一样支持配合 input_audio.format(例如 wav)传入原始 base64。每种最多 8 个,并要求 VLM 支持相应模态。每个问题的 name 可选但必须唯一(省略时响应的 name 为 null);choice 支持 2–255 个值(上限还受模型词表限制),score 支持 2–10 个等级,最多 64 个问题。响应中的 answers 数组与问题顺序一致:predicate 返回为真的概率,choice 返回选中值,score 返回零起始等级索引。LLM 和 VLM 均通过 logits 返回概率及 confidence,且 output_tokens 为 0。请将示例中的 model 替换为 geniex list 中的缓存模型名称,而非 GGUF 路径。

Python 客户端(OpenAI SDK)

由于服务器使用 OpenAI 协议,可直接将官方 openai Python 客户端指向本地端点,复用任意已有的 OpenAI 代码。先通过 pip install openai 安装,然后创建 client:
python
下面的示例都复用此 client。请把 model 替换为已拉取的模型;可选的 :<precision> 后缀(例如 Q4_0、Q4_K_M、Q8_0)选择量化变体——Q4_0 推荐用于 Hexagon NPU 上的 llama.cpp。详见支持的精度(量化)。

流式(Streaming)

按 delta 到达顺序逐段打印:
python

Chat completion(非流式)

单次请求、单次响应,不启用流式——标准的 OpenAI chat.completions.create 形式。enable_think=False 关闭 Qwen3 默认的 <think>…</think> 推理前缀,让回复内容更干净。
python
输出:
usage.prompt_tokens 为完整 prompt 长度,包含从 KV cache 复用的 tokens;usage.prompt_tokens_details.cached_tokens 为其中复用的部分(未命中时为 0),timings.prompt_n 为实际计算的 tokens。QAIRT 模型暂不统计复用,其 prompt_tokens 只包含实际计算的 tokens。

分离推理内容(reasoning_content)

思考模型默认会把思维链放入 OpenAI 标准的 message.reasoning_content 字段,让 content 只保留干净的回复。仅在需要把原始推理保留在 message.content 时,才需在请求体中传入 reasoning_format="none"。
reasoning_format 与 enable_think 是两件事:enable_think=False 让模型不产生思维链;默认的 reasoning_format="deepseek" 让模型照常思考,但把思维链移出 content。取值 deepseek(默认)、deepseek-legacy 和 auto 均触发分离,none 则保持原样内联。工具调用请求同样生效(含流式):思维链会先分离出来,再对回复扫描工具调用。
python
流式响应同理——思维链以 delta.reasoning_content 增量返回,最终回复以 delta.content 返回。

工具调用(Tool calling)

函数/工具调用使用标准的 OpenAI tools schema。服务器会从模型生成的文本中解析工具调用(<tool_call>…</tool_call> 标签或 ```json 代码块),并以 OpenAI tool_calls 形式返回。VLM 也走同一条路径——模型可以先看图,再决定搜什么、调用工具。 下面的示例用 qualcomm/Qwen3-VL-4B-Instruct 演示两步 agentic 回路:(1) VLM 从照片中识别地标并调用 web_search;(2) 本地执行搜索并将结果回传,VLM 基于结果生成带依据的回复。
一次响应可能包含多个工具调用;请为每个 tool_call_id 回传一条 role: "tool" 消息。设置 parallel_tool_calls: false 可让 llama_cpp 模型每次最多返回一个调用(部分 template 可能忽略)。QAIRT 会忽略该选项。下方示例仅处理第一个调用。
Qwen3-VL 稳定触发工具调用需要注意两点:
  1. 用 system 消息显式说明 <tool_call>…</tool_call> 的格式(Qwen3-VL 的 chat template 对该格式的先验没有 Qwen3 纯文本版本那么强)。
  2. 第二轮不再传入 tools=,也不要再回传图像——否则 VLM 会重复调用工具,且视觉编码器会对同一张图再跑一次。
先安装示例使用的搜索库(pip install ddgs —— DuckDuckGo,无需 API key):
python
输出(依赖 DuckDuckGo 实时结果,具体文字随当天返回内容而变化):

其他端点

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