服务调用

接口测试

服务启动后，可以通过模型列表接口检查服务是否正常响应。

curl http://127.0.0.1:8000/v1/models

输出示例：

以下输出仅作格式参考，具体数值以实际运行环境为准。

{
  "models": [
    {
      "name": "Qwen3.6-35B-A3B-Q4.gguf",
      "model": "Qwen3.6-35B-A3B-Q4.gguf",
      "modified_at": "",
      "size": "",
      "digest": "",
      "type": "model",
      "description": "",
      "tags": [
        ""
      ],
      "capabilities": [
        "completion",
        "multimodal"
      ],
      "parameters": "",
      "details": {
        "parent_model": "",
        "format": "gguf",
        "family": "",
        "families": [
          ""
        ],
        "parameter_size": "",
        "quantization_level": ""
      }
    }
  ],
  "object": "list",
  "data": [
    {
      "id": "Qwen3.6-35B-A3B-Q4.gguf",
      "aliases": [],
      "tags": [],
      "object": "model",
      "created": 1781495975,
      "owned_by": "llamacpp",
      "meta": {
        "vocab_type": 2,
        "n_vocab": 248320,
        "n_ctx_train": 262144,
        "n_embd": 2048,
        "n_params": 34660610688,
        "size": 19572951552
      }
    }
  ]
}

文本生成模型调用

curl 调用

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen",
    "messages": [{"role": "user", "content": "你好，介绍一下北京"}],
    "temperature": 0.7,
    "max_tokens": 128
  }'

参数说明

参数	说明
http://127.0.0.1:8000/v1/chat/completions	Chat Completions 接口地址，需要与服务启动时的 --host、--port 保持一致。
Content-Type: application/json	指定请求体格式为 JSON。
model	模型名称。llama.cpp 服务端会接收该字段，通常可填写当前服务加载的模型别名或模型名称。
messages	对话消息列表。每条消息包含 role 和 content。
role	消息角色。用户输入使用 user。
content	用户输入内容。文本生成模型中填写字符串。
temperature	采样温度。数值越高，输出随机性越强。
max_tokens	本次请求最多生成的 token 数。

Embedding 模型调用

启动 Embedding 服务后，可以通过 OpenAI 兼容的 /v1/embeddings 接口生成文本向量。

curl 调用

curl -f http://127.0.0.1:18081/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3-embedding",
    "input": [
      "今天天气很好",
      "今天阳光明媚",
      "如何编译 llama.cpp"
    ],
    "encoding_format": "float"
  }'

参数说明

参数	说明
http://127.0.0.1:18081/v1/embeddings	Embedding 接口地址，需要与服务启动时的 --host、--port 保持一致。
Content-Type: application/json	指定请求体格式为 JSON。
model	模型名称，需要填写服务启动时通过 --alias 设置的 qwen3-embedding。
input	待生成向量的文本，可以传入单个字符串或字符串数组。
encoding_format	向量编码格式。设置为 float 时返回浮点数数组。

多模态图片调用

使用本地图片进行测试

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "请描述这张图片"},
        {"type": "image_url", "image_url": {"url": "file://test-1.jpeg"}}
      ]
    }],
    "temperature": 0.7,
    "max_tokens": 128
  }'

参数	说明
model	模型名称。多模态请求需要服务启动时已加载对应的模型和 mmproj 文件。
messages	对话消息列表。多模态请求中，content 使用数组形式传入文本和图片。
role	消息角色。用户输入使用 user。
content	多模态输入内容列表，可以同时包含文本和图片。
type: "text"	表示该元素为文本输入。
text	文本提示词内容。
type: "image_url"	表示该元素为图片输入。
image_url.url	图片路径。使用本地图片时填写file:// 路径，例如测试图片在/dev/images/test-1.jpg，服务启动时--media-path设置为/dev/images, 则此处图片路径应设为file://test-1.jpeg。
temperature	采样温度。数值越高，输出随机性越强。
max_tokens	本次请求最多生成的 token 数。