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 # Windows

3. 安装 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.git

5. 在 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. 常见问题排查

1. 下载失败：检查网络连接，或尝试手动下载模型并指定本地路径。
2. 内存不足：all-mpnet-base-v2 加载后约占用 1.2 GB 内存。如果内存紧张，可考虑使用更小的模型（如 all-MiniLM-L6-v2）。
3. 版本冲突：如果遇到sentence-transformers与torch版本不兼容，请根据官方文档调整版本。
4. 编码速度慢：启用 GPU 或调整batch_size可显著提升速度。

8. 总结

本文介绍了在 TextGen 中启用 embedding 功能并安装 all-mpnet-base-v2 模型的完整步骤。通过上述配置，你可以轻松将文本转换为高质量的向量表示，并应用于语义搜索、聚类、推荐等场景。如果你在实践过程中遇到问题，欢迎在 TextGen 官方社区或 GitHub 仓库中反馈。