TextGen 启用 embedding 并安装 all-mpnet-base-v2 模型教程
1. 引言
TextGen 是一个功能强大的文本生成与处理框架，支持通过 embedding 模型将文本转换为向量表示，从而进行语义搜索、相似度计算等任务。all-mpnet-base-v2 是 Sentence‑Transformers 提供的一个高性能预训练模型，在多种语义相似度任务上表现优异。本文将详细介绍如何在 TextGen 中启用 embedding 功能，并安装、配置 all-mpnet-base-v2 模型。
2. 环境准备
在开始之前，请确保你的系统已安装以下基础环境：
- Python 3.8 或更高版本
- pip 包管理工具
- 可用的网络连接（用于下载模型）
建议使用虚拟环境（如 venv 或 conda）隔离项目依赖：
# 创建并激活虚拟环境（以 venv 为例） python -m venv textgen-env source textgen-env/bin/activate # Linux/macOS # 或 textgen-env\Scripts\activate # Windows3. 安装 TextGen 与相关依赖
首先安装 TextGen，参考前一篇文章 ：TextGen for Local LLM-CSDN博客
如果你已经安装了 TextGen，可以通过以下命令安装 embedding 扩展：
pip install sentence-transformers torch transformers --index-url <your proxy url> # https://nexusoss.xxx.com/repository/pypi-proxy/simple注意：embedding 功能依赖于sentence-transformers和torch，请确保它们已正确安装。
4. 下载并安装 all-mpnet-base-v2 模型
all-mpnet-base-v2 模型可以通过sentence-transformers直接加载，或从 Model Scope 下载模型文件，我使用了 git clone 的方式下载：
git clone https://www.modelscope.cn/sentence-transformers/all-mpnet-base-v2.git5. 在 TextGen 中启用 embedding
TextGen 提供了统一的接口(OPENEDAI_EMBEDDING_MODEL 和 OPENEDAI_EMBEDDING_DEVICE)来使用 embedding 模型，我在TextGen根目录创建 start.sh文件，并设置此文件可执行权限，在文件中设置参数：(我的模型放在 textgen-4.9/user_data/models/embedding/ 下)
start.sh
export OPENEDAI_EMBEDDING_MODEL="/home/ai/textgen-4.9/user_data/models/embedding/all-mpnet-base-v2" export OPENEDAI_EMBEDDING_DEVICE="auto" # "cpu" or "cuda" or auto echo "EMBEDDING_MODEL: $OPENEDAI_EMBEDDING_MODEL" echo "EMBEDDING_DEVICE: $OPENEDAI_EMBEDDING_DEVICE" ## 啟動參數 ## --model Qwen3.5-4B-Q4_K_M.gguf ## --extensions rag #有問題，chainlit-ui 呼叫 TextGen API 會出現 500 Internal Server Error，原因不明，暫時先不使用 rag 擴充功能 #./textgen --no-electron --listen --listen-host 0.0.0.0 --model Qwen3.5-4B-Q4_K_M.gguf nohup ./textgen --no-electron --listen --listen-host 0.0.0.0 --model Qwen3.5-4B-Q4_K_M.gguf > textgen-$(date +%Y%m%d).log 2>&1 & echo $! # show PID以下是一个完整的示例，展示如何初始化 TextGen 并启用 all-mpnet-base-v2 进行文本向量化：
user_data/extensions/rag/0.embedding_model_test.py
import os import numpy as np import torch from sentence_transformers import SentenceTransformer # 修改为你的本地模型目录 MODEL_DIR = os.environ.get("MODEL_DIR", "/home/ai/textgen-4.9/user_data/models/embedding/all-mpnet-base-v2") # 加载模型（从本地文件夹） model = SentenceTransformer(MODEL_DIR) # 如有可用 GPU，可移动模型到 GPU（可选） if torch.cuda.is_available(): model = model.to('cuda') sentences = [ "这是第一个句子。", "这是第二个句子。", "这是第三条文本，用来演示相似度。" ] # 编码为 numpy 向量 embeddings = model.encode(sentences, convert_to_tensor=False, show_progress_bar=False) emb = np.array(embeddings, dtype=np.float32) # 计算余弦相似度（小数据集示例） emb_norm = emb / np.linalg.norm(emb, axis=1, keepdims=True) sims = emb_norm @ emb_norm.T print("sentences:", sentences) print("embeddings shape:", emb.shape) print("cosine similarity matrix:", sims)执行上面的程式：
python user_data/extensions/rag/0.embedding_model_test.py运行结果：
Loading weights: 100%|█████████████████████████████████████████████████████████████████████████████████████████████| 199/199 [00:00<00:00, 4662.79it/s]
sentences: ['这是第一个句子。', '这是第二个句子。', '这是第三条文本，用来演示相似度。']
embeddings shape: (3, 768)
cosine similarity matrix: [[1.0000002 0.88622326 0.6373426 ]
[0.88622326 1.0000002 0.6343377 ]
[0.6373426 0.6343377 0.9999999 ]]
6. 配置与优化建议
- 设备选择：默认情况下模型会在 CPU 上运行。如果你有 GPU，可以通过
model = SentenceTransformer('all-mpnet-base-v2', device='cuda')加速。
export OPENEDAI_EMBEDDING_DEVICE="cuda" # "cpu" or "cuda" or auto- 批量处理：对大量文本进行编码时，建议使用
model.encode(sentences, batch_size=32)以提高效率。 - 缓存机制：TextGen 支持对已计算的向量进行缓存，避免重复计算。可以在初始化时设置
use_cache=True。 - 模型版本：确保使用的
sentence-transformers版本与模型兼容，推荐使用最新稳定版。
7. 常见问题排查
- 下载失败：检查网络连接，或尝试手动下载模型并指定本地路径。
- 内存不足：all-mpnet-base-v2 加载后约占用 1.2 GB 内存。如果内存紧张，可考虑使用更小的模型（如 all-MiniLM-L6-v2）。
- 版本冲突：如果遇到
sentence-transformers与torch版本不兼容，请根据官方文档调整版本。 - 编码速度慢：启用 GPU 或调整
batch_size可显著提升速度。
8. 总结
本文介绍了在 TextGen 中启用 embedding 功能并安装 all-mpnet-base-v2 模型的完整步骤。通过上述配置，你可以轻松将文本转换为高质量的向量表示，并应用于语义搜索、聚类、推荐等场景。如果你在实践过程中遇到问题，欢迎在 TextGen 官方社区或 GitHub 仓库中反馈。