Text Generation WebUI API密钥配置与国内网络设置教程

一、准备工作：先弄清API Key用在什么地方

Text Generation WebUI 是常见的本地大模型工具，适合在个人电脑、工作站或服务器上运行开源语言模型。很多用户提到“API Key配置”，其实可能对应两类场景：一类是把 WebUI 启动为本地接口服务，让其他程序调用；另一类是连接外部模型服务或插件，需要填写服务商提供的密钥。配置前先确认目标，否则容易把本地访问令牌、模型平台密钥和登录密码混在一起。

本教程以常见部署流程为主，覆盖账号注册、密钥获取、本地写入、接口测试和国内网络设置。适用对象包括：已经安装 Text Generation WebUI、希望用脚本调用本地模型、需要接入第三方推理服务、或在国内环境中安装依赖较慢的用户。操作前建议准备 Python 环境、Git、显卡驱动、浏览器，以及一个用于保存配置的独立文件夹。

二、账号注册：按需选择模型或服务平台

如果只在本机运行已下载的大模型，通常不需要注册外部账号；启动 WebUI 后即可通过浏览器使用。但如果要下载部分受控模型、调用在线推理接口，或使用需要身份验证的插件，就需要到对应平台创建账号。注册时建议使用长期可用的邮箱，开启二次验证，并把平台名称、注册邮箱、用途记录在本地文档中，方便后续排查。

注册完成后，进入平台的个人设置、开发者设置或访问令牌页面，通常可以看到“Create token”“New API key”“Access Tokens”等入口。创建密钥时，权限尽量选择最小范围，例如只读下载模型、仅推理调用，不要随意勾选管理权限。密钥名称可以写成“textgen-webui-local”或“server-test”，便于日后识别和撤销。

三、密钥获取与保存：不要把Key写进公开文件

生成 API Key 后，平台一般只完整显示一次，复制后应立即保存到本机安全位置。不要把密钥写进公开仓库、截图、群聊、教程评论区，也不要放在共享网盘。更稳妥的做法是使用系统环境变量、专用配置文件或本机密钥管理工具。若团队多人使用，应为不同人员创建不同密钥，出现异常时可以单独停用。

在 Windows 中，可以通过“系统属性—环境变量”添加变量，例如将变量名设置为 PROVIDER_API_KEY，变量值粘贴对应密钥。PowerShell 临时测试可使用 $env:PROVIDER_API_KEY="你的密钥"。在 macOS 或 Linux 中，可在终端执行 export PROVIDER_API_KEY="你的密钥"，若要长期生效，可写入用户级 shell 配置文件。修改后需要重新打开终端或重启 WebUI，配置才会被读取。

四、Text Generation WebUI本地接口启动思路

Text Generation WebUI 支持以网页界面运行，也可以开启 API 服务供其他应用调用。常见做法是在启动参数中启用 API，例如在启动脚本中加入 --api。若需要兼容 OpenAI 风格接口，可根据当前版本启用对应扩展或参数，实际名称会随版本变化，建议以项目页面和本地 help 输出为准。启动后，终端会显示访问地址和端口，默认只绑定本机时，外部设备无法访问，这是较安全的状态。

如果需要局域网内其他设备调用，可使用监听地址参数让服务绑定到内网地址，并配合访问控制。不要直接把接口暴露到公网；如果确有远程调用需求，应至少配置反向袋里、访问令牌、白名单、日志审计和系统防火墙规则。用于测试的本地服务可以采用 http://127.0.0.1:7860 或 http://127.0.0.1:5000 一类地址，具体端口以启动日志为准。

五、在WebUI中填写外部API Key

部分扩展或模型后端会在 WebUI 页面提供 Key 输入框。进入对应扩展设置页后，将密钥粘贴到指定字段，保存并重启服务。若页面没有输入框，通常需要通过环境变量或配置文件传入。建议不要直接修改核心源码，因为版本更新后容易被覆盖，也不利于排查问题。

如果 WebUI 部署在服务器上，推荐把密钥写入服务启动脚本引用的环境变量中，而不是写进命令历史。以 systemd、Docker 或进程管理工具运行时，也应检查日志是否会打印完整密钥。任何包含密钥的配置文件都应限制读取权限，备份时也要确认不会同步到公共位置。

六、国内网络设置：提高依赖安装与模型下载稳定性

国内用户常见问题集中在依赖安装慢、模型文件下载中断、连接外部接口超时。处理思路是优先使用合规、稳定的镜像源和可直连资源。Python 依赖可配置国内 PyPI 镜像，Git 仓库可选择可访问的同步源，模型文件可优先使用官方提供的分片下载、断点续传或国内镜像站。下载大模型前先确认磁盘空间，7B 模型常需要数 GB 到十几 GB，量化版本体积更小，更适合普通显卡。

在 pip 安装依赖时，可临时指定镜像源，也可以写入 pip 配置文件。若 conda 环境下载较慢，可切换到稳定的国内软件源。需要注意的是，镜像源只解决依赖获取速度，不代表能替代服务账号权限；如果模型本身要求登录或授权，仍需按平台规则申请。下载中断时不要反复删除重来，优先使用支持续传的工具，校验文件大小和哈希值，避免加载损坏模型导致报错。

七、接口测试：用最小请求验证配置是否成功

配置完成后，不要直接接入复杂业务，先做最小化测试。启动 WebUI，加载一个较小模型，观察终端是否出现加载成功、显存占用、端口监听等信息。再使用浏览器或接口调试工具访问健康检查地址或文本生成接口，发送一段简短提示词，确认能返回内容。若使用外部平台密钥，则测试一个低成本、短输出请求即可，避免因循环调用造成资源浪费。

测试时重点看三类信息：一是身份验证是否通过，若返回 unauthorized、invalid key、permission denied，通常是密钥错误、权限不足或环境变量未生效；二是模型是否成功加载，若出现 CUDA out of memory，多半是显存不足，可改用量化模型、降低上下文长度或切换 CPU/分层加载；三是网络是否稳定，若超时或连接重置，可更换镜像源、延长超时参数或分批下载。

八、常见问题与排查方法

问题一：填了 API Key 仍提示无效。先确认复制时没有多余空格、换行或引号；再确认密钥是否已被撤销、是否具备当前接口权限；最后重启 WebUI 和终端会话，确保环境变量被新进程读取。

问题二：本地接口能打开，其他设备访问不到。检查启动服务是否只监听 127.0.0.1。如果要内网访问，需要绑定到合适地址，并放行本机防火墙端口。出于安全考虑，只建议在可信内网中开放，并设置访问限制。

问题三：安装依赖失败。先升级 pip、setuptools、wheel，再根据显卡和系统版本选择匹配的深度学习框架。不要混用多个 Python 环境；遇到版本冲突时，创建新的虚拟环境往往比在旧环境里反复修补更省时间。

问题四：模型下载完成但无法加载。检查模型格式是否匹配当前加载器，例如 GGUF、GPTQ、AWQ、Transformers 权重对应不同后端。还要确认 tokenizer 文件是否完整，目录层级是否正确，文件名不要随意改动。

九、安全边界与实用建议

API Key 的本质是身份凭据，一旦泄露，别人可能以你的身份调用服务或访问受限资源。发现异常调用、日志中间出现陌生请求、密钥疑似外泄时，应立即停用旧密钥并创建新密钥，同时检查项目文件、部署日志和共享记录。生产环境中不要使用个人测试密钥，建议按项目单独创建，设置额度提醒和调用限制。

本地大模型接口也要有边界意识。不要让未授权用户访问你的 WebUI，不要把包含隐私、商业合同、客户资料的内容直接提交到不可信服务。用于学习测试时，优先选择小模型和本地推理；用于业务场景时，应补充身份验证、访问日志、输入过滤、输出审查和备份方案。

最后建议保留一份部署清单：系统版本、Python 版本、Text Generation WebUI 提交版本、模型名称、启动参数、端口、密钥变量名、镜像源配置和常见报错处理记录。这样在升级、迁移或回滚时，可以快速复现环境，避免每次都从零排查。对多数用户来说，稳定运行比追求最新版本更重要；升级前先备份配置和模型索引，确认插件兼容后再切换。