Spaces:
Sleeping
Download README.md from GiantPandas/Chat: direct link, hf CLI and curl.
- Browser
- Download file 18.3 kB
-
https://huggingface.co/spaces/GiantPandas/Chat/resolve/main/README.md
- Command line
-
hf download hf://spaces/GiantPandas/Chat/README.md
-
curl -L -o README.md https://huggingface.co/spaces/GiantPandas/Chat/resolve/main/README.md
A newer version of the Gradio SDK is available: 6.32.0
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
在 Hugging Face 创建 Space,SDK 选择 Gradio。账号允许时可选择 CPU Basic;也支持保持 ZeroGPU,见下方启动兼容说明。
将以下四个文件上传到 Space 仓库的根目录,不要保留压缩包外层目录:
app.pychat_backend.pyrequirements.txtREADME.md
在 Settings → Variables and secrets → New secret 中添加:
名称 值 INF_BASE_URL你的接口根地址或 /v1地址;设置为 Secret,不要使用公开 VariableINF_API_KEY你的实际 API Key,不包含 Bearer前缀按下面的环境变量表配置需要的选项。保存配置并等待 Space 完成构建、重启。
打开应用,模型默认选择
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,再作为多张图片上传。 |