Chat / README.md
GiantPandas's picture
Upload 4 files
945f538 verified
|
Raw History Blame Contribute Delete
18.3 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade
metadata
title: vLLM Chat Studio
emoji: 💬
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.31.0
python_version: '3.12'
app_file: app.py
pinned: false

vLLM Chat Studio

一个可部署到 Hugging Face Spaces 的中文图文对话界面,支持文字、单张或多张图片,用于调用 vLLM 的 OpenAI 兼容接口。Space 只运行网页和 HTTP 转发逻辑,模型继续运行在你已有的 vLLM 服务上,因此前端 Space 不需要 GPU。

接口地址和 API Key 仅从服务端私有环境变量读取,代码中没有默认接口地址。默认模型 ID 为 test-model。程序使用 /v1/models 获取模型列表,向 /v1/chat/completions 发送对话请求。图片在 Space 服务端读取并转换为 OpenAI image_url 数据块,再发送给模型接口。

1. 部署到 Hugging Face Spaces

  1. 在 Hugging Face 创建 Space,SDK 选择 Gradio。账号允许时可选择 CPU Basic;也支持保持 ZeroGPU,见下方启动兼容说明。

  2. 将以下四个文件上传到 Space 仓库的根目录,不要保留压缩包外层目录:

    • app.py
    • chat_backend.py
    • requirements.txt
    • README.md
  3. 在 Settings → Variables and secrets → New secret 中添加:

    名称 值
    INF_BASE_URL 你的接口根地址或 /v1 地址;设置为 Secret,不要使用公开 Variable
    INF_API_KEY 你的实际 API Key,不包含 Bearer 前缀
  4. 按下面的环境变量表配置需要的选项。保存配置并等待 Space 完成构建、重启。

  5. 打开应用,模型默认选择 test-model,可以直接发送消息。如果网关没有开放 /v1/models,不影响使用已填写的模型 ID 发送聊天请求。需要使用其他模型时可手动输入,或设置 INF_MODEL。

INF_BASE_URL 和 INF_API_KEY 都应创建为 Secret。 Hugging Face 的普通 Variables 适合非敏感配置;它们可以在 Space 设置中公开查看。Secrets 和 Variables 都能在 Gradio 服务端通过环境变量读取,但可见性不同。接口地址和域名不会放进前端配置或请求预览;显示到网页的错误信息也会隐藏已配置的接口地址、域名和 Key。旧 Git 提交中已有的内容不会因这次更新自动删除。

如果你希望只有自己使用,创建 Private Space;也可以配置下面的 APP_USERNAME、APP_PASSWORD 启用应用登录。公开且未配置登录的 Space,其访问者可以通过这个界面使用你的服务端 Key 调用模型。

tests/ 目录是可选的测试代码,不影响 Space 启动。

从上一版升级到图文版:一起替换 app.py、chat_backend.py 和 requirements.txt,并同步更新 README.md;提交后等待 Space 重建、重启。 图片处理逻辑和依赖都有更新,不能只替换 app.py。API Key、模型地址和现有 Secrets 无需更改。

ZeroGPU 启动兼容

如果启动页显示 No @spaces.GPU function detected during startup,说明 Space 正在使用 ZeroGPU,而应用没有注册该运行环境要求的 GPU 函数。这个界面把请求发送给已有的 vLLM 服务,本身不执行 GPU 推理。

此版本已按 Hugging Face 官方 API 转发应用指引增加兼容处理:检测到平台设置的 SPACES_ZERO_GPU 时,注册一个不会被聊天操作调用的空 GPU 函数。发送、重新生成和模型发现仍使用普通服务端回调,不申请 GPU。无需自己设置 SPACES_ZERO_GPU,也不要给真实聊天函数添加 GPU 装饰器。HF 的 Gradio 运行环境已提供 spaces 包;普通 CPU 和本地运行不导入它。

另一种处理方式是到 Settings → Space hardware 切换到 CPU Basic(如果你的账号有此选项)。硬件选择在 Space 设置中完成;在 README YAML 中增加 hardware: 不会切换硬件。

当前 Hugging Face 对新建 CPU Gradio/Docker Space 有账号套餐要求,CPU Basic 无小时费用并不代表所有账号都能使用;符合条件的免费账号可使用 ZeroGPU。以账号设置页面和官方说明为准。

程序还提供模块级 demo 对象,供 HF 热重载器发现,消除 Launching demo not found in __main__ 提示。pip 的 root 用户警告不导致上述 ZeroGPU 启动失败。

2. 环境变量

名称 设置位置 默认值 作用
INF_API_KEY Secret 无,必填 请求头中的 API Key。只填写 Key 本身。
INF_BASE_URL Secret 无,必填 支持填写服务根地址或带 /v1 的地址;程序会规范化接口路径。
INF_MODEL Variable 或 Secret test-model 默认模型 ID。适合 /v1/models 不可用或需要固定模型的网关。
INF_VERIFY_SSL Variable true 是否验证 HTTPS 证书。设为 false 时对应你原来 curl -k 的行为。
INF_TIMEOUT Variable 600 HTTP 请求超时配置,单位为秒。
MAX_CONCURRENT_REQUESTS Variable 8 应用允许的并发生成请求数,按后端承载能力调整。
MAX_IMAGES_PER_REQUEST Variable 8 单次请求图片总数上限,包含多轮模式携带的历史图片;本次新上传的图片也计入。
MAX_IMAGE_MB Variable 20 每张上传图片及其转换结果的文件大小上限,单位 MiB。
MAX_IMAGE_PIXELS Variable 40000000 单张图片的像素数上限,即约 4000 万像素;按宽 × 高检查。
MAX_IMAGE_PAYLOAD_MB Variable 64 单次请求所有图片 Data URL 的累计编码字节上限,包含 Base64、Data URL 前缀及历史图片;单位 MiB。
APP_USERNAME Secret 或 Variable 空 可选的应用登录用户名。需与 APP_PASSWORD 同时设置。
APP_PASSWORD Secret 空 可选的应用登录密码。需与 APP_USERNAME 同时设置。

对应你的 curl -k

如果当前网关需要跳过证书校验,在 Space 中增加 Variable:

INF_VERIFY_SSL=false

这会跳过证书身份校验。证书正常时保持默认 true 即可。这个设置不改变 API Key 的读取方式。

模型名称怎么填

填写 /v1/models 返回的 id。如果启动 vLLM 时使用了 --served-model-name,应填写该名称;否则以你的实际接口返回结果为准。界面支持手动输入,不要求模型列表接口一定可用。

3. 对话模式

单次问答

每次请求仅包含当前 System Prompt、当前问题和本次上传的图片。此前显示过的文字和图片不作为下一次请求的上下文,适合测试提示词、OCR 和对比调用参数。

多轮聊天

每次请求包含当前 System Prompt、已完成的历史问答及其图片,以及当前问题和新上传的图片。第一轮上传图片后,可以直接继续追问,不必每轮重复上传。可通过历史轮数参数限制发送最近多少轮完整问答,0 表示发送全部已完成历史;超出所保留轮数的旧图片不会继续发送。

两种模式各自保存当前会话的记录;切换模式时不会把单次问答的内容混入多轮上下文。历史保存在当前应用会话中,不是永久聊天存档。

生成操作

  • 发送:使用当前参数调用接口。
  • 停止生成:中止当前生成,保留已显示的部分内容,并恢复该问题的文字和上传附件。
  • 重新生成:重新回答最后一个问题及其图片,使用当前参数;不会将该问题重复追加为新一轮。
  • 清空:清理当前模式的聊天记录。

失败或主动停止的部分回答不会作为“已完成回答”传入后续多轮请求。可以使用重新生成重试该问题。

图片输入与保真

在消息输入框中上传图片后可以同时输入问题,也可以只发图片。支持一次选择多张图片;聊天记录显示图片预览,文字和图片作为同一轮问题发送。

  • 默认图片长边上限为 **0**,表示客户端保持原始分辨率。JPEG、PNG、WebP 在不需要调整时保留原始字节,避免为 OCR 或文档解析默认降低清晰度;模型服务仍可能按自身视觉处理配置缩放。
  • 可以指定图片长边上限,例如 2048,按比例缩小超过该尺寸的图片;不会放大较小的图片。修改后重新生成会从最后一轮的原始上传附件重新处理,因此也可以恢复为原尺寸。
  • 图片如带有需矫正的 EXIF 方向,会按方向校正;BMP 和单页静态 TIFF 会转为 PNG。这些情况下需要重新编码。
  • 动画图片和多页图片会明确拒绝,避免只发送其中一帧或一页。本项目不接收 PDF、音频或视频。
  • 图片数限制计算的是整个请求:当前图片加上保留的历史图片。超过限制时,可减少携带历史轮数、清空当前会话或在单次问答模式下重新发送。

“本次请求 JSON”中的图片 Base64 会以占位文字隐藏,便于查看消息结构;实际发给 vLLM 的请求仍包含完整图片数据。该预览不会删除或缩减实际请求中的图片。MAX_IMAGE_PAYLOAD_MB 按编码后的 Data URL 总字节数检查,因此它与原始图片文件大小之和不同;Base64 通常会让数据体积增加约三分之一。

vLLM 服务端要求

所选模型必须支持视觉输入。纯文本模型即使使用同一个聊天接口,也不能因为界面允许上传就获得图像理解能力。

如果要在一个请求里携带多张图片,请确保 vLLM 服务端允许足够的图片数量。例如,在你原有的启动命令中使用:

--limit-mm-per-prompt '{"image": 8}'

这是 vLLM 启动参数,不应粘贴到界面的高级请求 JSON 中。上限应覆盖当前图片及历史图片的总和,并结合模型能力和显存调整;Space 中的 MAX_IMAGES_PER_REQUEST 不会自动修改 vLLM 配置。

4. 调用参数

参数 说明
max_tokens 本次最多生成的 token 数,必须为正整数。它不是输入加输出的总上下文长度。
temperature 控制随机性;0 用于接近贪心解码的设置。
top_p 核采样阈值,范围 (0, 1]。
top_k 候选 token 数;-1 或 0 表示不启用此限制,或填写正整数。
min_p 相对于最高概率 token 的概率阈值,范围 [0, 1]。
repetition_penalty 重复惩罚,必须大于 0;1 表示不施加该惩罚。
presence_penalty 对已出现 token 的惩罚,范围 [-2, 2]。
frequency_penalty 按已出现频次计算的惩罚,范围 [-2, 2]。
seed 随机种子;-1 表示不显式发送。固定 seed 不保证跨模型、版本或服务配置完全复现。
stop 停止字符串。可以每行一个,或填写 JSON 字符串数组。
流式输出 开启后逐步显示回答;关闭后等待完整结果。
流式 usage 请求后端在流式响应中返回 token 用量;部分网关不支持,可关闭。
历史轮数 多轮模式发送最近多少轮完整问答;0 为全部。
沿用服务端采样默认值 勾选后省略并禁用 temperature、top_p、top_k、min_p、repetition_penalty、presence_penalty、frequency_penalty 七项控件;max_tokens、seed、stop、Thinking 和高级 JSON 仍生效。
思考模式 默认 / 开启 / 关闭。开启或关闭通过 chat_template_kwargs.enable_thinking 传递,实际是否生效取决于模型模板。
图片最长边 · 像素 0 保持原图;正整数表示按比例缩小超过该长边尺寸的上传图片,重新生成时也按当前值处理原始附件。

界面可查看请求 JSON、返回的 token 用量、总耗时和首个文本片段延迟。首个文本片段延迟可作为 TTFT 的近似观察值;它包含客户端等到首个回答或推理文本片段的时间。请求预览只包含请求体,不包含 Authorization 请求头;图片 Base64 已替换为便于阅读的占位文字。

如果接口返回独立的 reasoning 或 reasoning_content,界面会将它们与最终回答分开展示。后续上下文使用模型的回答文本,不会把界面中的思考面板格式回传给模型。

模型的上下文窗口由 vLLM 部署配置决定。历史太长或 max_tokens 太大时,后端可能拒绝请求;减少历史轮数或输出上限后再发送。

Stop 输入示例

每行一个字符串:

<END>
</answer>

需要换行停止符时,使用 JSON 表示更明确:

["\n\n", "<END>"]

5. 高级 JSON 参数

高级 JSON 会合并到最终请求体的顶层。与采样面板重名时,高级 JSON 的值优先,实际结果可以在请求预览中检查。

不要包一层 extra_body:extra_body 是 OpenAI Python SDK 的辅助参数,本项目直接发送 HTTP JSON,所以应直接填写它里面的字段。

messages、model、stream、n 由界面控制,不能通过高级 JSON 覆盖。本项目提供文字和图片对话,不运行工具调用循环,也不接受工具或函数定义。

关闭支持该选项的模型的思考模式

{
  "chat_template_kwargs": {
    "enable_thinking": false
  }
}

这需要模型的 chat template 支持 enable_thinking;不是所有模型都接受或使用该选项。

添加停止 token

{
  "stop_token_ids": [12345]
}

12345 仅是格式示例,应替换为当前模型 tokenizer 对应的实际 token ID。

请求结构化 JSON 输出

以下是支持 structured_outputs 的 vLLM 版本可使用的示例:

{
  "structured_outputs": {
    "json": {
      "type": "object",
      "properties": {
        "answer": {"type": "string"},
        "confidence": {"type": "number"}
      },
      "required": ["answer", "confidence"],
      "additionalProperties": false
    }
  }
}

结构化输出字段随 vLLM 版本不同可能有差异,具体以你部署版本的文档为准。本界面传递这些参数;能否执行由后端模型、解码支持和网关共同决定。

6. 本地运行

使用 Python 3.12,在项目目录执行:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

在终端输入私有接口地址和 API Key,再启动(不要把真实值写入仓库文件):

read -rsp 'API base URL: ' INF_BASE_URL
export INF_BASE_URL
printf '\n'
read -rsp 'API Key: ' INF_API_KEY
export INF_API_KEY
printf '\n'
python app.py

如果本地服务同样需要 curl -k 的证书行为,可在启动前执行:

export INF_VERIFY_SSL=false

接口地址没有内置默认值。下面仅为占位示例,不包含真实私有配置:

export INF_BASE_URL='https://your-api.example.com/v1'
export INF_MODEL='test-model'
python app.py

运行自带测试:

python -m unittest discover -s tests -v

测试使用模拟 HTTP 响应,不需要真实 API Key,也不调用你的在线模型服务。

7. 常见问题

现象 排查方向
No @spaces.GPU function detected during startup 使用本版本的 app.py,保留 ZeroGPU;或在账号允许时切换到 CPU Basic。
提示未配置 Key 检查 Space Secret 是否准确命名为 INF_API_KEY,保存后等待重启。
HTTP 401 / 403 检查 Key 是否有效、是否有接口权限;Key 的值不要带 Bearer 前缀。
模型列表为空或获取失败 手动填写模型 ID,或设置 INF_MODEL;有些网关只开放聊天接口。
HTTP 404 确认网关是否使用标准 /v1/chat/completions 路径,以及 INF_BASE_URL 是否包含正确路径前缀。
Model not found 使用 /v1/models 返回的模型 ID 或 --served-model-name 配置值。
HTTPS 证书错误 对需要 curl -k 的服务设置 INF_VERIFY_SSL=false;证书正常时使用 true。
参数不支持 / HTTP 400 先清空高级 JSON、使用服务端默认采样参数,再检查你的 vLLM 版本支持哪些字段。
流式输出异常 尝试关闭流式 usage;仍异常时关闭流式输出,检查网关是否支持 SSE 转发。
输入超过上下文长度 减少历史轮数、缩短问题或降低 max_tokens。
未显示 token 用量 后端或网关可能没有返回 usage;界面不会将缺失的用量当作零。
上传图片后接口报不支持多模态 确认选择的是视觉语言模型,且 vLLM 部署支持该模型的图片输入。
提示图片数量超限 检查当前图片与多轮历史图片的总数,以及 Space 和 vLLM 两侧各自的数量限制。
提示图片文件过大或像素过多 先在本地缩小或压缩图片,再重新上传;需要时再调整管理员设置的上限。
提示动画或多页文件不支持 将需要识别的帧或页面导出为独立 PNG/JPEG,再作为多张图片上传。

8. 参考文档