SingVL_S1_4B_GGUF / docs /protocol.md
m1ngcheng's picture
Add files using upload-large-folder tool
5374914 verified
|
Raw History Blame Contribute Delete
5.67 kB

GGUF protocol reference

HTTP 输入输出格式

接口:POST /v1/systemone,Content-Type 为 application/json。这不是 OpenAI 的 messages/chat-completions 接口。

字段 类型 说明
state JSON 值,必填 字符串直接使用;对象等序列化为紧凑 JSON。图像请求可用 {}。
questions 非空对象,必填 键为用户自定义 question ID,值为题目对象;按顺序逐题计算。
images 字符串数组,可选 最多 4 张,支持 base64、data URL、--image-root 内文件路径。路径指服务端文件,不是客户端路径。
return_details 布尔,可选 为 true 时返回 evaluation_trace(token 信息、位置和候选 logits)。

题目对象:type 必填,取 choice、noul、score;instructions 为问题文本,可省略(空字符串)。

  • choice:criteria 为按插入顺序排列的 2~256 个候选组成的对象,如 {"red":"Red","blue":"Blue"}。输出 choice 是原键 red,不是内部索引 AA。
  • noul:criteria 可省略,默认 {"true":"Yes","false":"No"};自定义时必须恰好包含 true 和 false 两个键。输出 noul 是 true 的概率,不是布尔值。
  • score:criteria 必须为 2~10 个等级描述组成的有序数组。输出为从 0 开始的等级期望值,可为小数,同时返回每级概率和 legend。

state 和 instructions 在现有协议中直接拼接,不自动插入分隔符;需要分隔时,在 state 末尾显式保留空格或换行。不要自行添加 chat 标记、答案前缀或模型输出。若 state 没写 <image>,图片占位符会按 images 顺序加到前面;若显式写了占位符,数量必须与图片数完全一致。图片标记放在 state,不放在 instructions。普通用户只需填写 JSON,不需要指定内部 token ID。

单题文本请求:

{"state":"The color is red. ","questions":{"color":{"type":"choice","instructions":"Which color is named?","criteria":{"red":"Red","blue":"Blue"}}}}

对应 Q8_0 CPU 示例响应(浮点数按实际后端可能略有不同):

{
  "model": "sing-vl-s1",
  "answers": {
    "color": {
      "type": "choice",
      "choice": "red",
      "probabilities": {"red": 0.9966803216653017, "blue": 0.0033196783346983094}
    }
  },
  "usage": {"input_tokens": 56, "output_tokens": 0}
}

model 字段保留既有协议标识 sing-vl-s1,与 GGUF 文件名不同。output_tokens=0 表示直接读取 logits,没有自回归生成答案文本;多题 input_tokens 是每题完整输入长度之和。带图请求额外返回 image_tokens;return_details=true 时额外返回 evaluation_trace。

choice/noul/score 的完整多题请求见 examples/request_text_readme.json;双图请求见 examples/request_two_images.json。原始 prompt、候选 IDs/logits 和后处理对照见 examples/input_output.json。

错误响应形如 {"error":"..."}:非法 JSON/参数或不可读图片通常为 400,超大或缺少长度的请求体为 413,不支持的题型/超长输入/图片数量等为 422,后端执行失败为 500。请求体最大 64 MiB,客户端应发送 Content-Length(上面的 curl 会自动设置)。

数据流程

用户 JSON → Processor.prepare() → 推理后端加载 GGUF,执行整题前向计算并返回候选 logits → Processor.finish() → choice/noul/score 结果。

from processing import Processor

processor = Processor("config")
items = processor.prepare(request["state"], request["questions"], images)
answers = {}
for item in items:
    # 由用户实现 backend:完整题目前向计算,返回以下候选的 logits,顺序必须一致。
    logits = backend(item)
    answers[item["question_id"]] = processor.finish(item, logits)

这里的 images 为按用户顺序解码后的 PIL 图片;JSON 的 base64/路径解码示例见 examples/llama_cpp/serve.py。backend 是用户实现的接口占位符,本示例不声称存在通用硬件后端。

每个 item 包含 prompt、展开后的 input_ids、candidate_token_ids、rgb_images、image_features 和用于参考的 batch。后端选择自己的输入形式:llama.cpp 使用提示词和 RGB 图片,在内部编码图像;不要把 RGB 图片和已经展开的 image token 再重复插入。batch 是 Transformers 风格的参考输入,不是可直接传给任意 GGUF 引擎的统一张量协议。

模型索引按配置中固定的 256 个 token 顺序分配给本题有序候选。后端返回本题候选 logits,而不是已经归一化的概率;后处理仅在本题候选间做 softmax,返回原 criteria 键。noul 返回 true 概率,score 返回从 0 开始的等级期望值。支持纯文本和最多 4 张图片,不支持视频。

后端必须满足的约定

  1. GGUF 的 qwen35.attention.causal=false 必须实际生效;所有输入的 full-attention 层双向,GDN 保持因果。
  2. 一道题的完整文本和图像应一起处理,不能沿用会破坏双向可见性的普通因果分块 prefill。本参考适配器使用一次 llama_process,batch/ubatch 容量覆盖完整输入。
  3. 每道题独立清空 KV 和循环状态;不能跨题复用前缀缓存。保持图像顺序、图像 token 展开及 M-RoPE 坐标一致。
  4. 不把答案拼回输入。读取最后有效输入位置的 logits;按照 candidate_token_ids 取值。固定索引、候选顺序、图像预处理和提示词均为协议的一部分。

不能仅用任意 GGUF 聊天程序加载权重就认定实现等价。