本地部署大模型完整指南text-generation-webui 从硬件选型到参数调优一次讲透【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen想在自己电脑上跑一个本地大模型local LLM又常被环境配置和参数选择卡住text-generation-webui 是一个开源桌面应用支持文本生成、视觉理解、工具调用和 OpenAI 兼容 API数据全程留在本机。这篇文章按真实使用顺序把流程串起来先按硬件挑对依赖文件再走最短路径启动 Web 界面然后把常用开关固化到参数文件接着在界面上调 temperature、top_p 等生成参数最后覆盖 Docker 容器化部署和几类高频报错的排查思路。硬件自查按显卡类型选依赖文件装依赖前先看机器。项目把不同硬件的依赖清单放在 requirements/full/ 目录下启动时会按你选择的 GPU 类型自动取用对应文件你主要需要知道我属于哪一类硬件环境依赖文件说明NVIDIA 显卡requirements/full/requirements.txt默认选项走 CUDA 加速AMD 显卡requirements/full/requirements_amd.txtROCm 路线Apple M 系列芯片requirements/full/requirements_apple_silicon.txtARM 架构 MacApple Intel 芯片requirements/full/requirements_apple_intel.txt老款 Intel Mac无任何显卡requirements/full/requirements_cpu_only.txt纯 CPU 推理速度偏慢但能跑目录里还有一份 requirements/full/requirements_nowheels.txt当你遇到预编译包装不上的报错多见于较老的 CPU时可以换它重试。判断方法很简单Windows 下看设备管理器里的显卡型号Linux 下跑nvidia-smi有输出就是 NVIDIA 卡Mac 点左上角关于本机看芯片是 M 系列还是 Intel。最短启动路径克隆仓库并打开 Web 界面依赖文件不用你手动安装启动脚本会代劳。流程只有三步git clone https://gitcode.com/GitHub_Trending/te/textgen cd textgen ./start_linux.sh # macOS 换成 ./start_macos.shWindows 双击 start_windows.bat脚本内部做的事情以 start_linux.sh 为例在仓库内installer_files/目录装一个独立的 Miniforge 环境创建 Python 环境并安装依赖最后调用 one_click.py 完成首次初始化。首次运行要下载较多内容耐心等待即可。两个容易踩的坑安装路径里不能有空格脚本检测到含空格的路径会直接退出克隆目录时避开My Projects这类名字。成功标志是终端停住、浏览器打开http://localhost:7860看到 Chat、Default、Parameters 等标签页即说明 Web 界面已就绪。参数持久化CMD_FLAGS.txt 怎么写每次启动都手动敲参数不现实。项目用 user_data/CMD_FLAGS.txt 做持久化文件里每行一个启动参数#开头是注释每次启动时自动生效。仓库自带的示例就是# 每次启动都生效的参数 --listen --api --auto-launch几个高频开关按想解决什么问题来记手机/其他设备访问界面加--listen让 7860 端口对局域网开放注意开启后程序会提示设置登录口令gradio auth。调用 OpenAI 风格 API加--api默认在 5000 端口提供接口可用--api-key设访问密钥。省去手动开浏览器加--auto-launch。显存紧张时 8 位加载加--load-in-8bit或--load-in-4bit基于 bitsandbytes 的量化加载。确认只用 CPU 跑加--cpu避免程序探测显卡导致加载行为不符合预期。验证方式改完文件重启一次看终端启动参数里是否包含对应项或在 API 页面确认接口已可用。生成参数调优temperature、top_p 与 max_new_tokens 的取舍模型一次生成一个 token每一步都从下一个 token 的概率分布里挑选Parameters 标签页里的大部分参数都是在控制这个挑选过程完整说明见 docs/03 - Parameters Tab.md。新手只需盯住下面四个原则是每次只动一个用同一个问题重新生成几轮来对比效果temperature随机性主旋钮越低输出越稳定、越老实越高越发散。事实问答、总结类任务建议 0.6~0.8创意写作可以放到 1.0 以上。验证同一问题连续生成 3 次输出几乎一致说明偏保守开始胡编说明偏高。top_p核采样只从累计概率达到该阈值的那批 token 里抽选。日常从 0.9 起步想给模型更多长尾词的空间就往 1.0 靠。它和 top_k 是同类功能建议只调其中一个避免叠加过度。max_new_tokens回复上限别设得比需要的更大——它会挤占提示词空间prompt 实际可用长度按truncation_length - max_new_tokens计算设太高反而让长上下文被截断。普通聊天 512 足够写长文再往上调或勾选 auto_max_new_tokens 让长度自适应上下文。repetition_penalty / presence_penalty治复读模型反复说同一句话时把 repetition_penalty 从 1.0 提到 1.05~1.2 试试提太高会出现用词怪异、前后不搭出现这种情况就回调。另外别从零调参Parameters 页的 Preset 下拉框提供社区投票选出的内置预设如 Divine Intellect、Midnight Enigma直接载入再微调是更快的路线自己调好的组合也可以用 按钮存成预设仓库在 user_data/presets/ 下预置了 Creative.yaml、Deterministic.yaml、Top-P.yaml 三份可参考。常见故障分场景排查现象一加载或生成时报 CUDA out of memory显存不足做法按代价从低到高先减小truncation_length界面里Truncate the prompt up to this length上下文越占显存再换量化加载在 CMD_FLAGS.txt 里加--load-in-8bit更紧张就--load-in-4bit还不行就换更小参数量或 GGUF 量化版模型。验证重启后模型能完整加载、首次生成不再 OOM速度可以接受即可。现象二生成速度慢速度主要取决于模型大小、量化方式和上下文长度而不是 temperature 这类采样参数——别指望调采样能变快。有效的杠杆换小模型或量化版把上下文长度调低CPU 场景下用--threads指定接近物理核心数的线程数。验证对比调整前后同样长度的回复耗时。现象三局域网其他设备打不开页面确认 CMD_FLAGS.txt 里有--listen并重启防火墙放行 7860 端口访问地址用http://主机IP:7860而不是 localhost。仍不行时看终端里 gradio 的输出通常会直接给出监听地址和端口能发现只监听了 127.0.0.1这类问题。现象四老机器装依赖失败换 requirements/full/requirements_nowheels.txt 重试纯 CPU 机器则确认选中的是 requirements_cpu_only.txt并在启动参数里显式加--cpu。Docker 容器化部署服务器与多环境方案需要在服务器上长期跑、或本机已有复杂的 Python 环境怕依赖互相污染时用容器是更干净的隔离方案。项目在 docker/ 下提供 nvidia、amd、intel、cpu 四种 compose 配置以 NVIDIA 为例最短路径是完整说明见 docs/09 - Docker.mdcd textgen/docker/nvidia cp ../.env.example .env # 按 nvidia-smi 的 compute capability 改 TORCH_CUDA_ARCH_LIST docker compose up --build前提Docker Compose v2.17NVIDIA 机器另装 NVIDIA Container Toolkit。构建完成后同样访问http://localhost:7860。注意一点容器重建会清空内部状态建议在 compose 文件旁建一个user_data/目录模型、预设、人物卡片都会挂载保存进去持久启动参数就写在其中的 CMD_FLAGS.txt 里与前面手动部署的用法完全一致。下一步可执行的动作清单按上表确认自己属于哪类硬件跑对应系统的 start 脚本完成首次启动确认 7860 页面能打开。在 user_data/CMD_FLAGS.txt 写入--listen --api --auto-launch重启验证一次。载入一个内置 Preset 作为调参起点用同一问题连测 3 轮确定自己的 temperature 与 top_p 区间后存为新预设。显存不足的话依次试降上下文 →--load-in-8bit→--load-in-4bit→ 换小模型。计划部署到服务器时按 Docker 小节构建docker/nvidia镜像并建好user_data/持久化目录。想深入某个功能模块直接读 docs/ 下对应章节比翻代码更快。【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 本地部署大模型完整指南：text-generation-webui 从硬件选型到参数调优一次讲透
本地部署大模型完整指南text-generation-webui 从硬件选型到参数调优一次讲透【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen想在自己电脑上跑一个本地大模型local LLM又常被环境配置和参数选择卡住text-generation-webui 是一个开源桌面应用支持文本生成、视觉理解、工具调用和 OpenAI 兼容 API数据全程留在本机。这篇文章按真实使用顺序把流程串起来先按硬件挑对依赖文件再走最短路径启动 Web 界面然后把常用开关固化到参数文件接着在界面上调 temperature、top_p 等生成参数最后覆盖 Docker 容器化部署和几类高频报错的排查思路。硬件自查按显卡类型选依赖文件装依赖前先看机器。项目把不同硬件的依赖清单放在 requirements/full/ 目录下启动时会按你选择的 GPU 类型自动取用对应文件你主要需要知道我属于哪一类硬件环境依赖文件说明NVIDIA 显卡requirements/full/requirements.txt默认选项走 CUDA 加速AMD 显卡requirements/full/requirements_amd.txtROCm 路线Apple M 系列芯片requirements/full/requirements_apple_silicon.txtARM 架构 MacApple Intel 芯片requirements/full/requirements_apple_intel.txt老款 Intel Mac无任何显卡requirements/full/requirements_cpu_only.txt纯 CPU 推理速度偏慢但能跑目录里还有一份 requirements/full/requirements_nowheels.txt当你遇到预编译包装不上的报错多见于较老的 CPU时可以换它重试。判断方法很简单Windows 下看设备管理器里的显卡型号Linux 下跑nvidia-smi有输出就是 NVIDIA 卡Mac 点左上角关于本机看芯片是 M 系列还是 Intel。最短启动路径克隆仓库并打开 Web 界面依赖文件不用你手动安装启动脚本会代劳。流程只有三步git clone https://gitcode.com/GitHub_Trending/te/textgen cd textgen ./start_linux.sh # macOS 换成 ./start_macos.shWindows 双击 start_windows.bat脚本内部做的事情以 start_linux.sh 为例在仓库内installer_files/目录装一个独立的 Miniforge 环境创建 Python 环境并安装依赖最后调用 one_click.py 完成首次初始化。首次运行要下载较多内容耐心等待即可。两个容易踩的坑安装路径里不能有空格脚本检测到含空格的路径会直接退出克隆目录时避开My Projects这类名字。成功标志是终端停住、浏览器打开http://localhost:7860看到 Chat、Default、Parameters 等标签页即说明 Web 界面已就绪。参数持久化CMD_FLAGS.txt 怎么写每次启动都手动敲参数不现实。项目用 user_data/CMD_FLAGS.txt 做持久化文件里每行一个启动参数#开头是注释每次启动时自动生效。仓库自带的示例就是# 每次启动都生效的参数 --listen --api --auto-launch几个高频开关按想解决什么问题来记手机/其他设备访问界面加--listen让 7860 端口对局域网开放注意开启后程序会提示设置登录口令gradio auth。调用 OpenAI 风格 API加--api默认在 5000 端口提供接口可用--api-key设访问密钥。省去手动开浏览器加--auto-launch。显存紧张时 8 位加载加--load-in-8bit或--load-in-4bit基于 bitsandbytes 的量化加载。确认只用 CPU 跑加--cpu避免程序探测显卡导致加载行为不符合预期。验证方式改完文件重启一次看终端启动参数里是否包含对应项或在 API 页面确认接口已可用。生成参数调优temperature、top_p 与 max_new_tokens 的取舍模型一次生成一个 token每一步都从下一个 token 的概率分布里挑选Parameters 标签页里的大部分参数都是在控制这个挑选过程完整说明见 docs/03 - Parameters Tab.md。新手只需盯住下面四个原则是每次只动一个用同一个问题重新生成几轮来对比效果temperature随机性主旋钮越低输出越稳定、越老实越高越发散。事实问答、总结类任务建议 0.6~0.8创意写作可以放到 1.0 以上。验证同一问题连续生成 3 次输出几乎一致说明偏保守开始胡编说明偏高。top_p核采样只从累计概率达到该阈值的那批 token 里抽选。日常从 0.9 起步想给模型更多长尾词的空间就往 1.0 靠。它和 top_k 是同类功能建议只调其中一个避免叠加过度。max_new_tokens回复上限别设得比需要的更大——它会挤占提示词空间prompt 实际可用长度按truncation_length - max_new_tokens计算设太高反而让长上下文被截断。普通聊天 512 足够写长文再往上调或勾选 auto_max_new_tokens 让长度自适应上下文。repetition_penalty / presence_penalty治复读模型反复说同一句话时把 repetition_penalty 从 1.0 提到 1.05~1.2 试试提太高会出现用词怪异、前后不搭出现这种情况就回调。另外别从零调参Parameters 页的 Preset 下拉框提供社区投票选出的内置预设如 Divine Intellect、Midnight Enigma直接载入再微调是更快的路线自己调好的组合也可以用 按钮存成预设仓库在 user_data/presets/ 下预置了 Creative.yaml、Deterministic.yaml、Top-P.yaml 三份可参考。常见故障分场景排查现象一加载或生成时报 CUDA out of memory显存不足做法按代价从低到高先减小truncation_length界面里Truncate the prompt up to this length上下文越占显存再换量化加载在 CMD_FLAGS.txt 里加--load-in-8bit更紧张就--load-in-4bit还不行就换更小参数量或 GGUF 量化版模型。验证重启后模型能完整加载、首次生成不再 OOM速度可以接受即可。现象二生成速度慢速度主要取决于模型大小、量化方式和上下文长度而不是 temperature 这类采样参数——别指望调采样能变快。有效的杠杆换小模型或量化版把上下文长度调低CPU 场景下用--threads指定接近物理核心数的线程数。验证对比调整前后同样长度的回复耗时。现象三局域网其他设备打不开页面确认 CMD_FLAGS.txt 里有--listen并重启防火墙放行 7860 端口访问地址用http://主机IP:7860而不是 localhost。仍不行时看终端里 gradio 的输出通常会直接给出监听地址和端口能发现只监听了 127.0.0.1这类问题。现象四老机器装依赖失败换 requirements/full/requirements_nowheels.txt 重试纯 CPU 机器则确认选中的是 requirements_cpu_only.txt并在启动参数里显式加--cpu。Docker 容器化部署服务器与多环境方案需要在服务器上长期跑、或本机已有复杂的 Python 环境怕依赖互相污染时用容器是更干净的隔离方案。项目在 docker/ 下提供 nvidia、amd、intel、cpu 四种 compose 配置以 NVIDIA 为例最短路径是完整说明见 docs/09 - Docker.mdcd textgen/docker/nvidia cp ../.env.example .env # 按 nvidia-smi 的 compute capability 改 TORCH_CUDA_ARCH_LIST docker compose up --build前提Docker Compose v2.17NVIDIA 机器另装 NVIDIA Container Toolkit。构建完成后同样访问http://localhost:7860。注意一点容器重建会清空内部状态建议在 compose 文件旁建一个user_data/目录模型、预设、人物卡片都会挂载保存进去持久启动参数就写在其中的 CMD_FLAGS.txt 里与前面手动部署的用法完全一致。下一步可执行的动作清单按上表确认自己属于哪类硬件跑对应系统的 start 脚本完成首次启动确认 7860 页面能打开。在 user_data/CMD_FLAGS.txt 写入--listen --api --auto-launch重启验证一次。载入一个内置 Preset 作为调参起点用同一问题连测 3 轮确定自己的 temperature 与 top_p 区间后存为新预设。显存不足的话依次试降上下文 →--load-in-8bit→--load-in-4bit→ 换小模型。计划部署到服务器时按 Docker 小节构建docker/nvidia镜像并建好user_data/持久化目录。想深入某个功能模块直接读 docs/ 下对应章节比翻代码更快。【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考