TextGen 本地大模型部署实战：从克隆到 API 调用的完整路线-育师

TextGen 本地大模型部署实战：从克隆到 API 调用的完整路线

【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen

TextGen 是一个开源的本地大模型桌面应用与 Web UI，支持文本、视觉、工具调用，并提供 OpenAI/Anthropic 兼容的 API，全程离线、无遥测。适合想在个人电脑或服务器上跑私有 LLM、又不想配置云服务环境的开发者与新手。下面按硬件选路线，再给最短可跑通的部署步骤和调优参数。

按硬件选部署路线

你的环境	推荐路线	依赖文件	对应章节
NVIDIA GPU（Windows/Linux）	一键脚本或 venv + CUDA 版 llama.cpp	`requirements/full/requirements.txt`或`requirements/portable/requirements.txt`	最小可用部署
AMD GPU	一键脚本，选 AMD 分支	`requirements/full/requirements_amd.txt`	最小可用部署
无 GPU 的 x86 服务器	venv + CPU 依赖	`requirements/full/requirements_cpu_only.txt`	最小可用部署
Apple Silicon / Intel Mac	一键脚本或 venv + MPS 依赖	`requirements/full/requirements_apple_silicon.txt`	最小可用部署
容器化服务器	Docker Compose	`docker/nvidia/`、`docker/cpu/`等	Docker 容器化部署

依赖文件分requirements/full/（含 Transformers、训练、绘图等完整后端）和requirements/portable/（仅 llama.cpp 后端，体积更小）两套，按硬件后缀选择即可。

最小可用部署：venv 五步跑通

以 Linux/macOS 为例（Windows 把source venv/bin/activate换成venv\Scripts\activate）：

git clone https://gitcode.com/GitHub_Trending/te/textgen cd textgen python -m venv venv source venv/bin/activate

第 1 步成功标志：本地出现textgen/目录。
第 3 步成功标志：出现venv/目录。

安装依赖并启动：

pip install -r requirements/portable/requirements.txt --upgrade python server.py --portable --api --auto-launch

安装成功标志：终端无ERROR: Could not find a version that satisfies。
启动成功标志：浏览器自动打开http://127.0.0.1:7860，出现 Chat/Default/Parameters 等标签页。

放模型：从 Hugging Face 下载任意 GGUF 文件，放入user_data/models/，界面会自动识别，无需重启。Transformers 或 ExL3 等多文件模型需放在user_data/models/下的独立子文件夹中，且必须用 full 版安装。

不想手搭环境也可以直接跑 start_linux.sh（或start_windows.bat、start_macos.sh），脚本会自动装 Miniforge 环境，按提示选 GPU 厂商，装完同样访问http://127.0.0.1:7860。

启动参数持久化写法

两层配置，作用域不同：

持久化配置——写入 user_data/CMD_FLAGS.txt，每次启动server.py都会读取，适合固定的网络与加载策略：

--listen：绑定 0.0.0.0，允许局域网访问
--api：启用 OpenAI/Anthropic 兼容 API（默认端口 5000）
--model MODEL_NAME：启动时直接加载指定模型
--idle-timeout 60：闲置 60 分钟后自动卸载模型释放显存
--settings user_data/settings.yaml：从 YAML 加载默认界面设置

界面内即时配置——Parameters 标签页，改动立即生效且随会话保存，适合实验单个采样参数；两者冲突时以启动参数为准。核心生成参数与推荐区间：

参数	含义	推荐区间
`max_new_tokens`	单次生成上限，过高会挤占提示词截断空间	512–2048
`temperature`	随机性主旋钮，0 为确定性解码	0.7–1.2
`top_p`	核采样阈值，与 top_k 二选一即可	0.9–1.0
`min_p`	相对最高概率的淘汰线，替代 top_k 时更稳	0.02–0.1
`repetition_penalty`	重复惩罚，1 为关闭	1.0–1.2
截断长度	防止提示词超出模型上下文	模型 ctx − 512

现成参数组合可直接用user_data/presets/下的 Creative.yaml（min_p 0.02 + xtc 0.5）、Deterministic.yaml、Top-P.yaml，在 Preset 菜单中加载。

进阶场景

低显存量化加载

显存紧张时换 Transformers 后端并降精度（需 full 版依赖中的 bitsandbytes）：

--load-in-4bit --use_double_quant

4-bit + 双重量化下，8B 模型权重大约占 4.5–5GB 显存。配合--ctx-size 8192压低 KV cache，--gpu-layers控制放卡上的层数（llama.cpp 后端设-1为尽量全放）。纯 CPU 机器用--cpu --threads 8（8 为物理核心数）。

局域网远程访问

在user_data/CMD_FLAGS.txt追加--listen，重启后从局域网用http://<服务器IP>:7860访问。多人共用加--multi-user（不保存聊天记录）。注意--listen会向同网段所有设备暴露 UI，公共网络下请配合防火墙限制来源 IP。

Docker 容器化部署

以 NVIDIA 为例（AMD/Intel/CPU 换成docker/amd、docker/intel、docker/cpu）：

ln -s docker/nvidia/{Dockerfile,docker-compose.yml,.dockerignore} . cp docker/.env.example .env mkdir -p user_data/logs user_data/cache docker compose up --build

编辑本地.env：TORCH_CUDA_ARCH_LIST按显卡填（RTX 30 系 8.6、40 系 8.9），APP_RUNTIME_GID填宿主机id -g的输出，HOST_PORT默认 7860、API 端口HOST_API_PORT默认 5000。端口被占用时改.env里的HOST_PORT。完整说明见 docs/09 - Docker.md。

故障自查

现象	可能原因	处置动作
加载模型报 CUDA out of memory	量化精度或 ctx 过大	换 4-bit GGUF，或`--ctx-size 8192`、`--gpu-layers`减层
`pip install`报依赖冲突	系统 Python 装了冲突包	用 venv/conda 隔离，勿污染系统环境
局域网打不开 7860	未开`--listen`或防火墙拦截	`user_data/CMD_FLAGS.txt`加`--listen`，放行 7860/5000 端口
启动卡住或后端报错	requirements 选错硬件分支	按硬件换回对应`requirements_*.txt`重装，`--upgrade`
模型列表为空	模型没放对目录	GGUF 放`user_data/models/`根下，多文件模型放子文件夹
API 调不通	未加`--api`或端口不符	确认`--api`已启用，请求指向`http://127.0.0.1:5000`

下一步

用 docs/03 - Parameters Tab.md 逐条对照采样参数，把 Parameters 页的 top_k、tfs、penalty 系列各跑一轮对比输出差异。
阅读 docs/07 - Extensions.md，把 TTS、语音输入、机器翻译扩展放进user_data/extensions/试装。
参考user_data/tools/下的 web_search.py 写一个自己的工具函数，验证工具调用链路。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考