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_quant4-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 写一个自己的工具函数，验证工具调用链路。
【免费下载链接】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），仅供参考