Spaces:
Sleeping
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
18.3 kB
| 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。以账号设置页面和[官方说明](https://huggingface.co/docs/hub/spaces-overview)为准。 | |
| 程序还提供模块级 `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: | |
| ```text | |
| 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 服务端允许足够的图片数量。例如,在你原有的启动命令中使用: | |
| ```bash | |
| --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 输入示例 | |
| 每行一个字符串: | |
| ```text | |
| <END> | |
| </answer> | |
| ``` | |
| 需要换行停止符时,使用 JSON 表示更明确: | |
| ```json | |
| ["\n\n", "<END>"] | |
| ``` | |
| ## 5. 高级 JSON 参数 | |
| 高级 JSON 会合并到最终请求体的**顶层**。与采样面板重名时,高级 JSON 的值优先,实际结果可以在请求预览中检查。 | |
| 不要包一层 `extra_body`:`extra_body` 是 OpenAI Python SDK 的辅助参数,本项目直接发送 HTTP JSON,所以应直接填写它里面的字段。 | |
| `messages`、`model`、`stream`、`n` 由界面控制,不能通过高级 JSON 覆盖。本项目提供文字和图片对话,不运行工具调用循环,也不接受工具或函数定义。 | |
| ### 关闭支持该选项的模型的思考模式 | |
| ```json | |
| { | |
| "chat_template_kwargs": { | |
| "enable_thinking": false | |
| } | |
| } | |
| ``` | |
| 这需要模型的 chat template 支持 `enable_thinking`;不是所有模型都接受或使用该选项。 | |
| ### 添加停止 token | |
| ```json | |
| { | |
| "stop_token_ids": [12345] | |
| } | |
| ``` | |
| `12345` 仅是格式示例,应替换为当前模型 tokenizer 对应的实际 token ID。 | |
| ### 请求结构化 JSON 输出 | |
| 以下是支持 `structured_outputs` 的 vLLM 版本可使用的示例: | |
| ```json | |
| { | |
| "structured_outputs": { | |
| "json": { | |
| "type": "object", | |
| "properties": { | |
| "answer": {"type": "string"}, | |
| "confidence": {"type": "number"} | |
| }, | |
| "required": ["answer", "confidence"], | |
| "additionalProperties": false | |
| } | |
| } | |
| } | |
| ``` | |
| 结构化输出字段随 vLLM 版本不同可能有差异,具体以你部署版本的文档为准。本界面传递这些参数;能否执行由后端模型、解码支持和网关共同决定。 | |
| ## 6. 本地运行 | |
| 使用 Python 3.12,在项目目录执行: | |
| ```bash | |
| python -m venv .venv | |
| source .venv/bin/activate | |
| pip install -r requirements.txt | |
| ``` | |
| 在终端输入私有接口地址和 API Key,再启动(不要把真实值写入仓库文件): | |
| ```bash | |
| 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` 的证书行为,可在启动前执行: | |
| ```bash | |
| export INF_VERIFY_SSL=false | |
| ``` | |
| 接口地址没有内置默认值。下面仅为占位示例,不包含真实私有配置: | |
| ```bash | |
| export INF_BASE_URL='https://your-api.example.com/v1' | |
| export INF_MODEL='test-model' | |
| python app.py | |
| ``` | |
| 运行自带测试: | |
| ```bash | |
| 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. 参考文档 | |
| - [Hugging Face Spaces:环境变量与 Secrets](https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables) | |
| - [Hugging Face Spaces 配置参考](https://huggingface.co/docs/hub/spaces-config-reference) | |
| - [Hugging Face 官方:API 转发应用的 ZeroGPU 兼容方式](https://github.com/huggingface/skills/blob/main/skills/huggingface-spaces/references/inference-providers.md#hardware) | |
| - [Hugging Face 官方:ZeroGPU 注册回调要求](https://github.com/huggingface/skills/blob/main/skills/huggingface-spaces/references/zerogpu.md) | |
| - [Gradio 6 迁移指南](https://www.gradio.app/guides/gradio-6-migration-guide) | |
| - [vLLM OpenAI 兼容服务](https://docs.vllm.ai/en/latest/serving/online_serving/openai_compatible_server/) | |
| - [vLLM 多模态输入](https://docs.vllm.ai/en/stable/features/multimodal_inputs/) | |
| - [vLLM 多模态服务端配置](https://docs.vllm.ai/en/stable/configuration/engine_args/#multimodal-config) | |
| - [vLLM 思考输出](https://docs.vllm.ai/en/latest/features/reasoning_outputs/) | |
| - [vLLM SamplingParams](https://docs.vllm.ai/en/stable/api/vllm/sampling_params/) | |