通义千问3-Reranker-0.6B部署教程：Ubuntu 22.04 LTS环境从零配置

通义千问3-Reranker-0.6B部署教程：Ubuntu 22.04 LTS环境从零配置

1. 学习目标与环境准备

今天我要带大家从零开始，在Ubuntu 22.04 LTS系统上部署通义千问3-Reranker-0.6B模型。这是一个专门用于文本排序和相关性判断的AI模型，能够帮你快速找出最相关的文档内容。

学习完成后你将掌握：

• 如何在Ubuntu系统上搭建完整的Python环境
• 如何下载和配置通义千问重排序模型
• 如何启动Web服务并进行实际使用
• 遇到常见问题的解决方法

前置要求很简单：

• 一台运行Ubuntu 22.04 LTS的服务器或虚拟机
• 至少4GB内存（推荐8GB以上）
• 基本的Linux命令行操作经验

2. 环境搭建与依赖安装

2.1 系统更新与Python环境

首先让我们确保系统是最新状态，打开终端输入：

sudo apt update && sudo apt upgrade -y

接下来安装Python和相关工具：

sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip -y

检查Python版本是否正确：

python3 --version # 应该显示 Python 3.10.x

2.2 创建专用虚拟环境

为了避免依赖冲突，我们创建一个独立的Python环境：

# 创建项目目录 mkdir -p ~/qwen-reranker cd ~/qwen-reranker # 创建虚拟环境 python3 -m venv venv # 激活环境 source venv/bin/activate

激活后，你的命令行提示符前会出现(venv)字样，表示已经在虚拟环境中了。

2.3 安装必要依赖

现在安装模型运行所需的核心库：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu pip install transformers>=4.51.0 gradio>=4.0.0 accelerate>=0.30.0 safetensors>=0.4.3

安装要点说明：

• torch：PyTorch深度学习框架
• transformers：Hugging Face的模型库
• gradio：用于创建Web界面
• accelerate：优化模型推理速度
• safetensors：安全加载模型权重

3. 模型下载与配置

3.1 下载模型文件

通义千问3-Reranker-0.6B模型大约1.2GB，我们可以使用git大文件下载：

# 安装git大文件支持 sudo apt install git-lfs -y git lfs install # 下载模型（如果可以直接下载） mkdir -p models cd models

如果无法直接git下载，你也可以从Hugging Face模型库手动下载后放到~/qwen-reranker/models/目录。

3.2 创建启动脚本

创建一个简单的启动脚本start.sh：

#!/bin/bash cd ~/qwen-reranker source venv/bin/activate python app.py

给脚本添加执行权限：

chmod +x start.sh

3.3 创建主程序文件

创建app.py文件，这是我们的Web服务核心：

from transformers import AutoModelForSequenceClassification, AutoTokenizer import gradio as gr import torch import os # 模型路径 model_path = "./models/Qwen3-Reranker-0.6B" def load_model(): """加载模型和分词器""" print("正在加载模型，请稍候...") tokenizer = AutoTokenizer.from_pretrained(model_path) model = AutoModelForSequenceClassification.from_pretrained( model_path, torch_dtype=torch.float16, device_map="auto" ) print("模型加载完成！") return model, tokenizer def rerank_documents(query, documents, instruction=None, batch_size=8): """重排序文档""" try: # 确保输入格式正确 if isinstance(documents, str): documents = [doc.strip() for doc in documents.split('\n') if doc.strip()] # 准备输入 pairs = [[query, doc] for doc in documents] # 编码输入 inputs = tokenizer( pairs, padding=True, truncation=True, return_tensors="pt", max_length=32768, return_attention_mask=True ) # 模型推理 with torch.no_grad(): outputs = model(**inputs) scores = outputs.logits[:, 0].cpu().numpy() # 排序结果 ranked_results = sorted(zip(documents, scores), key=lambda x: x[1], reverse=True) return ranked_results except Exception as e: return f"处理出错: {str(e)}" # 加载模型 model, tokenizer = load_model() # 创建Gradio界面 interface = gr.Interface( fn=rerank_documents, inputs=[ gr.Textbox(label="查询文本", lines=2, placeholder="输入你要搜索的问题..."), gr.Textbox(label="文档列表", lines=6, placeholder="每行输入一个候选文档..."), gr.Textbox(label="任务指令（可选）", lines=2, placeholder="例如：Given a query, retrieve relevant passages..."), gr.Slider(minimum=1, maximum=32, value=8, step=1, label="批处理大小") ], outputs=gr.JSON(label="排序结果"), title="通义千问3-Reranker-0.6B 文档重排序", description="输入查询文本和候选文档列表，模型将返回按相关性排序的结果" ) if __name__ == "__main__": interface.launch(server_name="0.0.0.0", server_port=7860)

4. 启动与使用教程

4.1 启动Web服务

现在一切准备就绪，启动服务：

cd ~/qwen-reranker ./start.sh

首次启动需要一些时间加载模型（约30-60秒），成功后你会看到：

Running on local URL: http://0.0.0.0:7860

4.2 访问Web界面

打开浏览器，访问以下地址：

• 本地访问：http://localhost:7860
• 远程访问：http://你的服务器IP:7860

你会看到一个简洁的Web界面，包含查询框、文档输入框和可选指令框。

4.3 实际使用示例

示例1：英文查询测试

在查询框中输入：

What is the capital of China?

在文档框中输入（每行一个文档）：

Beijing is the capital of China, a bustling metropolitan city. Gravity is a fundamental force that governs the motion of celestial bodies. The Great Wall of China is one of the most famous historical landmarks. Python is a popular programming language for data science.

点击提交，模型会返回按相关性排序的结果，最相关的文档排在最前面。

示例2：中文查询测试

查询文本：

解释机器学习的基本概念

文档列表：

机器学习是人工智能的一个分支，让计算机通过数据自动学习改进。 今天天气晴朗，适合户外运动。 深度学习是机器学习的一种，使用神经网络处理复杂模式。 北京是中国的首都，拥有丰富的历史文化遗产。

你会看到模型准确识别出与机器学习相关的文档。

5. 常见问题解决

5.1 端口被占用错误

如果7860端口已被占用，可以更改端口：

# 修改app.py最后一行 interface.launch(server_name="0.0.0.0", server_port=7861) # 或者找出占用进程 sudo lsof -i:7860 sudo kill -9 <进程ID>

5.2 内存不足问题

如果遇到内存不足，可以尝试以下方法：

# 减小批处理大小 # 在app.py中修改默认批处理值 # 使用量化模型（如果可用） model = AutoModelForSequenceClassification.from_pretrained( model_path, torch_dtype=torch.float16, device_map="auto", load_in_8bit=True # 8位量化 )

5.3 模型加载失败

如果模型加载失败，检查：

1. 模型文件是否完整下载（约1.2GB）
2. 依赖库版本是否匹配
3. 磁盘空间是否充足

6. 进阶使用技巧

6.1 批量处理文档

如果你需要处理大量文档，可以修改代码支持批量处理：

def batch_rerank(queries, documents_list, batch_size=4): """批量重排序""" results = [] for i in range(0, len(queries), batch_size): batch_queries = queries[i:i+batch_size] batch_docs = documents_list[i:i+batch_size] # 处理每个批次 for query, docs in zip(batch_queries, batch_docs): result = rerank_documents(query, docs) results.append(result) return results

6.2 API接口调用

除了Web界面，你也可以通过API调用服务：

import requests import json def call_reranker_api(query, documents, instruction=None): url = "http://localhost:7860/api/predict" payload = { "data": [query, "\n".join(documents), instruction, 8] } response = requests.post(url, json=payload) return response.json() # 使用示例 results = call_reranker_api( "什么是人工智能", [ "人工智能是模拟人类智能的计算机系统", "天气预报说明天会下雨", "机器学习是AI的一个重要分支" ] )

7. 总结回顾

通过这个教程，我们成功在Ubuntu 22.04系统上部署了通义千问3-Reranker-0.6B模型。这个模型在文本重排序任务上表现优秀，支持中英文等多种语言，能够智能判断文档与查询的相关性。

关键要点回顾：

1. 使用虚拟环境隔离Python依赖，避免冲突
2. 模型需要约1.2GB磁盘空间和足够的内存
3. Web服务通过Gradio提供友好界面
4. 支持批量处理和API调用两种使用方式

下一步学习建议：

• 尝试不同的查询指令优化排序效果
• 集成到自己的搜索或推荐系统中
• 探索模型在多语言场景下的表现

这个重排序模型可以广泛应用于搜索引擎、文档检索、智能客服等场景，帮助提升内容的相关性和用户体验。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。