06 LlamaIndex入门

验证环境

uv venv -p 3.12
uv pip install llama-index

LlamaIndex官方文档

嵌入模型的部署方法

下面是为您整理好的 Xinference 与 TEI (Text Embeddings Inference) 部署 BAAI/bge-m3 的 Markdown 格式文档。您可以直接将其复制保存为 .md 文件使用。

1. Xinference 部署指南

Xinference 是一款功能强大的多模型管理平台。它不仅能部署大语言模型，还完美支持嵌入（Embedding）、重排（Reranker）以及图像、语音等多模态模型。

步骤一：安装 Xinference

建议在干净的 Python 虚拟环境中安装（推荐 Python 3.10+）：

# 加上 [all] 会自动安装大部分常用的模型后端推理引擎
pip install "xinference[all]"

步骤二：编写启动脚本

编写后台启动脚本 start_xinference.sh，用于在后台拉起 Xinference 本地服务：

cat << 'EOF' > start_xinference.sh
#!/bin/bash
# 启动 Xinference 核心守护服务，监听所有 IP 的 9997 端口
echo "Starting Xinference Supervisor & Worker..."
nohup xinference-local --host 0.0.0.0 --port 9997 > xinference.log 2>&1 &

# 等待 5 秒确保服务完全启动
sleep 5
echo "Xinference is running on port 9997."
EOF

步骤三：运行并启动模型

  1. 赋予脚本执行权限并启动：

chmod +x start_xinference.sh
./start_xinference.sh

  1. 使用命令行一键拉取并部署 bge-m3：

xinference launch --model-name bge-m3 --model-type embedding

服务会自动前往 Hugging Face（或 ModelScope 镜像源）下载 BAAI/bge-m3 的全量 PyTorch 权重并将其加载至显存中。

服务访问方式

  • OpenAI 兼容接口： http://<YOUR_IP>:9997/v1/embeddings

  • Web 控制台： 浏览器访问 http://<YOUR_IP>:9997 即可进入可视化管理后台。

警告

xinference在通过pip install xinference[all]快捷安装，然后再部署bge-m3的过程的时候报错找不到包。安装了也报错，没有深入。 这个库引入的东西太多了，可能会出现位置错误。尽量还是使用TEI部署嵌入模型更加简单可靠。

2. TEI (Text Embeddings Inference) 部署指南

TEI 是 Hugging Face 官方采用 Rust 编写的高性能嵌入/重排服务器。它支持动态批处理（Dynamic Batching），在生产环境中的吞吐量极高、延迟极低。

步骤一：准备环境

运行 TEI 强烈推荐使用官方 Docker 镜像，以避免在本地配置复杂的 Rust 与 CUDA 编译环境。请确保您的服务器已成功安装：

  1. Docker

  2. NVIDIA Container Toolkit（用于支持 Docker 调用 GPU）

步骤二：编写启动脚本

创建启动脚本 start_tei.sh。该脚本会拉起基于 GPU 的 TEI 容器，并将模型数据持久化在本地 data 目录下：

cat << 'EOF' > start_tei.sh
#!/bin/bash
# 1. 定义模型 ID 和本地模型权重缓存路径
MODEL_ID="BAAI/bge-m3"
VOLUME_PATH="$PWD/data"

# 创建缓存目录
mkdir -p $VOLUME_PATH

# 2. 通过 Docker 启动 TEI 容器 (使用 GPU 版本镜像)
echo "Starting HF Text Embeddings Inference (TEI) on Port 8080..."
docker run --gpus all \
  -p 8080:80 \
  -v $VOLUME_PATH:/data \
  --pull always \
  ghcr.io/huggingface/text-embeddings-inference:120-1.9 \
  --model-id $MODEL_ID \
  --max-client-batch-size 128 \
  --max-concurrent-requests 512
EOF

注意

在下载的时候 https://github.com/huggingface/text-embeddings-inference 需要区分显卡的版本，根据不同的gpu版本选择对应的标签；

核心参数说明：

  • --gpus all：映射宿主机所有 GPU。

  • --max-client-batch-size：单次客户端请求最大支持批量编码的文本数量。

  • --max-concurrent-requests：最大并发处理请求数，可根据显存和 CPU 核心数进行调整。

步骤三：运行启动命令

  1. 赋予脚本执行权限并后台运行：

chmod +x start_tei.sh
nohup ./start_tei.sh > tei_docker.log 2>&1 &

  1. 观察容器日志以确保模型加载成功：

tail -f tei_docker.log

服务访问方式

  • OpenAI 兼容接口： http://<YOUR_IP>:8080/v1/embeddings

  • 原生 API 接口： http://<YOUR_IP>:8080 (支持极速极简的原生 JSON 调用)

3. 部署方案对比快速选型

维度

Xinference

TEI (Text Embeddings Inference)

适用场景

团队研发、一站式多模型托管、Mac/PC 本地测试

极高并发的生产环境、企业级 RAG 检索微服务

底层核心

Python (支持 vLLM, llama.cpp 等后端)

Rust (专为 Embedding 和 Reranking 优化)

接口规范

兼容 OpenAI / 包含专属 API

兼容 OpenAI / 极速原生 API

易用性

极高（带 Web 控制台和可视化资源监控）

较高（纯 API/Docker 运行，无自带管理 UI）