文墨共鸣实战教程：构建支持API调用的水墨风语义相似度微服务

1. 引言：当算法遇见水墨

你有没有遇到过这样的场景？需要快速判断两段文字说的是不是一回事，比如检查用户反馈是否重复，或者判断两篇文章的核心观点是否一致。传统的关键词匹配方法经常“翻车”——字面不同但意思相同的句子，它识别不出来；而字面相似但意思迥异的句子，它又容易误判。

今天，我们来解决这个问题。我将带你手把手搭建一个既实用又有格调的语义相似度分析服务。它不仅内核强大，采用了阿里达摩院专为中文优化的StructBERT模型，能真正理解文字的深层含义，而且外表独特，披上了一层优雅的中国水墨风外衣。

想象一下，输入两段文字，系统不仅能给出精准的相似度分数，还能以一枚古朴的“朱砂印章”呈现结果，整个过程如同在宣纸上进行一场雅致的文墨品鉴。更重要的是，我们将把它封装成一个标准的API服务，让你可以轻松地在自己的项目里调用这个能力。

无论你是想为产品增加一个智能查重功能，还是想分析海量文本之间的关联，这个教程都能给你一个清晰、可落地的起点。我们开始吧。

2. 环境准备与项目初始化

2.1 系统与工具要求

在开始之前，请确保你的开发环境满足以下基本要求。别担心，要求很宽松。

• 操作系统：Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04+) 均可。
• Python版本：Python 3.8 到 3.10。推荐使用 3.8 或 3.9，兼容性最好。
• 包管理工具：pip 已安装并更新到最新版。
• 内存：建议至少 8GB RAM。模型加载需要一定内存，但推理时占用不大。
• 磁盘空间：预留约 1.5GB 空间用于下载模型和依赖。

2.2 创建项目与安装依赖

首先，我们创建一个干净的项目目录，并安装所有必需的库。

1. 创建项目文件夹并进入： 打开你的终端或命令行工具，执行以下命令。

   mkdir wenmo_gongming
   cd wenmo_gongming
   

2. 创建并激活虚拟环境（强烈推荐）： 使用虚拟环境可以避免包版本冲突，让项目更干净。

   # 创建虚拟环境
   python -m venv venv
   
   # 激活虚拟环境
   # 在 Windows 上：
   venv\Scripts\activate
   # 在 macOS/Linux 上：
   source venv/bin/activate
   

   激活后，你的命令行提示符前面通常会显示 (venv)。

3. 安装核心依赖： 我们将使用 pip 一次性安装所有需要的包。创建一个 requirements.txt 文件，或者直接运行下面的安装命令。

   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
   pip install transformers streamlit fastapi uvicorn python-multipart
   

   命令解释：

   • 第一行：安装 PyTorch（CPU版本）。如果你的机器有 NVIDIA GPU 并配置好了 CUDA，可以去 PyTorch 官网查找对应的 GPU 安装命令，速度会快很多。
   • 第二行：安装核心功能库。
     • transformers: Hugging Face 的库，用于加载和使用 StructBERT 模型。
     • streamlit: 用于快速构建我们水墨风的前端交互界面。
     • fastapi 和 uvicorn: 用于构建我们最终要实现的 API 服务。
     • python-multipart: 用于处理 API 中的表单数据。

   安装过程可能需要几分钟，取决于你的网络速度。

3. 核心代码实现：从模型加载到界面设计

环境准备好了，现在我们来写代码。我们会创建两个核心文件：一个用于模型推理和前端展示，另一个用于构建 API。

3.1 模型加载与推理函数

首先，我们创建一个 app.py 文件，这是 Streamlit 应用的入口，也包含了核心的模型逻辑。

# app.py
import streamlit as st
from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch
import torch.nn.functional as F
import time

# 设置页面为宽屏模式，并应用自定义CSS实现水墨风格
st.set_page_config(page_title="文墨共鸣 · 语义雅鉴", layout="wide")

# === 1. 加载模型与分词器 ===
@st.cache_resource # 使用Streamlit缓存，只加载一次模型
def load_model():
    model_name = "iic/nlp_structbert_sentence-similarity_chinese-large"
    print("正在加载模型，请稍候...")
    tokenizer = AutoTokenizer.from_pretrained(model_name)
    # 注意：此模型权重需要设置 weights_only=False 以兼容旧格式
    model = AutoModelForSequenceClassification.from_pretrained(model_name, trust_remote_code=True)
    model.eval() # 设置为评估模式
    print("模型加载完成！")
    return tokenizer, model

tokenizer, model = load_model()

# === 2. 核心相似度计算函数 ===
def calculate_similarity(text1, text2):
    """
    计算两段中文文本的语义相似度。
    参数:
        text1 (str): 第一段文本
        text2 (str): 第二段文本
    返回:
        float: 相似度得分 (0-1之间，越接近1越相似)
    """
    # 使用分词器准备模型输入
    inputs = tokenizer(text1, text2, return_tensors='pt', truncation=True, max_length=512)
    
    # 进行推理，不计算梯度以提升速度
    with torch.no_grad():
        outputs = model(**inputs)
    
    # 获取logits并计算概率
    logits = outputs.logits
    probs = F.softmax(logits, dim=-1)
    
    # 假设模型输出中，索引1代表“相似”的概率
    similarity_score = probs[0][1].item()
    return similarity_score

代码解读：

• load_model 函数：我们使用了 @st.cache_resource 装饰器。这意味着模型只会在第一次运行时下载和加载，之后会直接从缓存读取，大大加快应用启动速度。
• calculate_similarity 函数：这是核心。它接收两段文本，用分词器转换成模型能理解的数字格式，然后让模型预测，最后将输出转换成我们熟悉的 0 到 1 之间的相似度分数。

3.2 构建水墨风交互界面

接下来，我们在同一个 app.py 文件中，添加 Streamlit 代码来创建美观的界面。

# app.py (续)
# === 3. 自定义CSS，实现水墨风格 ===
st.markdown("""
<style>
/* 主背景 - 宣纸质感 */
.stApp {
    background-color: #f8f4e9;
    background-image: url('https://images.unsplash.com/photo-1541701494587-cb58502866ab?ixlib=rb-4.0.3&auto=format&fit=crop&w=2070&q=80');
    background-size: cover;
    background-blend-mode: overlay;
}

/* 主标题 - 书法风格 */
.main-title {
    font-family: 'Ma Shan Zheng', cursive, sans-serif;
    font-size: 3.5rem !important;
    color: #3a2618;
    text-align: center;
    margin-bottom: 0.5rem;
    text-shadow: 2px 2px 4px rgba(0,0,0,0.1);
}

/* 副标题 */
.sub-title {
    text-align: center;
    color: #7a6652;
    font-size: 1.2rem;
    margin-bottom: 2rem;
    font-style: italic;
}

/* 输入框样式 */
.stTextArea textarea {
    border: 1px solid #d4b483 !important;
    border-radius: 4px;
    background-color: rgba(255, 253, 248, 0.9);
}

/* 按钮样式 - 古风按钮 */
.stButton button {
    background-color: #8b4513 !important;
    color: white !important;
    border: none;
    border-radius: 20px;
    padding: 0.5rem 2rem;
    font-size: 1.1rem;
    font-weight: bold;
}
.stButton button:hover {
    background-color: #a0522d !important;
}

/* 结果展示区域 - 朱砂印章效果 */
.result-box {
    border: 2px dashed #c13c3c;
    border-radius: 15px;
    padding: 2rem;
    background-color: rgba(255, 248, 242, 0.95);
    text-align: center;
    margin-top: 2rem;
}
.score-text {
    font-family: 'Ma Shan Zheng', cursive, sans-serif;
    font-size: 4rem;
    color: #c13c3c;
    margin: 0;
}
.score-label {
    color: #7a6652;
    font-size: 1.5rem;
    margin-top: 0.5rem;
}
.interpretation {
    color: #5d5d5d;
    font-size: 1.1rem;
    margin-top: 1.5rem;
    line-height: 1.6;
}
</style>
""", unsafe_allow_html=True)

# === 4. 页面布局与交互 ===
# 标题区域
st.markdown('<h1 class="main-title">文墨共鸣</h1>', unsafe_allow_html=True)
st.markdown('<p class="sub-title">—— 基于 StructBERT 的语义相似度雅鉴系统</p>', unsafe_allow_html=True)

st.markdown("---")

# 创建两列布局，用于并排输入
col1, col2 = st.columns(2)

with col1:
    st.markdown("#### 📜 上文")
    text1 = st.text_area("请输入第一段文本", 
                         "人工智能正在改变世界。", 
                         height=150,
                         key="text1",
                         label_visibility="collapsed")

with col2:
    st.markdown("#### 📜 下文")
    text2 = st.text_area("请输入第二段文本", 
                         "AI技术深刻地影响着人类社会的发展。", 
                         height=150,
                         key="text2",
                         label_visibility="collapsed")

st.markdown("---")

# 居中放置分析按钮
col_btn1, col_btn2, col_btn3 = st.columns([1, 2, 1])
with col_btn2:
    analyze_button = st.button("🖋️ 开始品鉴", use_container_width=True)

# 当按钮被点击时，执行分析
if analyze_button and text1 and text2:
    with st.spinner('正在研磨墨韵，品鉴文心...'):
        # 为了展示加载效果，稍作等待
        time.sleep(0.5)
        score = calculate_similarity(text1, text2)
        score_percent = round(score * 100, 2)
        
        # 根据分数给出文言的解读
        if score >= 0.8:
            interpretation = "**异曲同工**。两段文字虽辞藻各异，然神韵相通，核心意旨高度契合。"
            emoji = "🎯"
        elif score >= 0.5:
            interpretation = "**和而不同**。文字间存在显著关联与共通之处，然在具体所指或细微处有所分殊。"
            emoji = "🤝"
        else:
            interpretation = "**云泥之别**。二者所言主题或视角迥异，关联甚微。"
            emoji = "☁️"
        
        # 使用自定义样式展示结果
        st.markdown(f"""
        <div class="result-box">
            <p class="score-label">文心契合度</p>
            <p class="score-text">{score_percent}</p>
            <p class="interpretation">{emoji} {interpretation}</p>
        </div>
        """, unsafe_allow_html=True)
        
        # 同时用普通文本输出，方便查看精确值
        st.caption(f"精确相似度得分: **{score:.4f}** (范围 0~1)")

elif analyze_button:
    st.warning("请完整输入上文与下文，再行品鉴。")

到这里，一个完整的水墨风语义相似度应用就完成了。运行 streamlit run app.py，你就可以在浏览器中看到并体验它了。

4. 进阶：封装为API微服务

一个只有界面的应用还不够方便。我们更希望其他程序也能调用这个功能。接下来，我们用 FastAPI 把它变成一个标准的 HTTP API 服务。

创建一个新的文件 api_server.py。

# api_server.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import uvicorn
from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch
import torch.nn.functional as F
import logging

# 配置日志
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# 定义API请求的数据模型
class SimilarityRequest(BaseModel):
    text1: str
    text2: str

# 定义API响应的数据模型
class SimilarityResponse(BaseModel):
    similarity_score: float
    text1: str
    text2: str
    message: str = "success"

# 初始化FastAPI应用
app = FastAPI(
    title="文墨共鸣语义相似度API",
    description="基于StructBERT的深度学习模型，提供中文文本语义相似度计算服务。",
    version="1.0.0"
)

# 全局加载模型（在实际生产环境中，需要考虑更优雅的加载和生命周期管理）
logger.info("正在启动并加载模型...")
MODEL_NAME = "iic/nlp_structbert_sentence-similarity_chinese-large"
tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
model = AutoModelForSequenceClassification.from_pretrained(MODEL_NAME, trust_remote_code=True)
model.eval()
logger.info("模型加载完成，API服务准备就绪。")

@app.get("/")
async def root():
    """API根路径，返回服务信息。"""
    return {
        "service": "文墨共鸣语义相似度API",
        "model": MODEL_NAME,
        "status": "running",
        "endpoint": "POST /api/v1/similarity"
    }

@app.post("/api/v1/similarity", response_model=SimilarityResponse)
async def calculate_similarity_api(request: SimilarityRequest):
    """
    计算两段文本的语义相似度。
    
    - **text1**: 第一段文本
    - **text2**: 第二段文本
    """
    try:
        if not request.text1.strip() or not request.text2.strip():
            raise HTTPException(status_code=400, detail="输入文本不能为空")
        
        # 准备模型输入
        inputs = tokenizer(
            request.text1, 
            request.text2, 
            return_tensors='pt', 
            truncation=True, 
            max_length=512
        )
        
        # 模型推理
        with torch.no_grad():
            outputs = model(**inputs)
        
        # 计算相似度分数
        logits = outputs.logits
        probs = F.softmax(logits, dim=-1)
        similarity_score = probs[0][1].item()
        
        logger.info(f"成功处理请求: text1长度={len(request.text1)}, text2长度={len(request.text2)}, 得分={similarity_score:.4f}")
        
        return SimilarityResponse(
            similarity_score=similarity_score,
            text1=request.text1,
            text2=request.text2
        )
        
    except Exception as e:
        logger.error(f"处理请求时发生错误: {e}")
        raise HTTPException(status_code=500, detail=f"内部服务器错误: {str(e)}")

# 健康检查端点
@app.get("/health")
async def health_check():
    """健康检查端点，用于监控服务状态。"""
    return {"status": "healthy"}

if __name__ == "__main__":
    # 启动服务，监听本地8000端口
    uvicorn.run(app, host="0.0.0.0", port=8000)

API服务使用方式：

1. 启动服务：在终端运行 python api_server.py。
2. 调用API：服务启动后，你可以使用任何 HTTP 客户端（如 curl、Postman 或 Python 的 requests 库）来调用它。

使用 curl 测试：

curl -X POST "http://127.0.0.1:8000/api/v1/similarity" \
-H "Content-Type: application/json" \
-d '{
  "text1": "人工智能正在改变世界。",
  "text2": "AI技术深刻地影响着人类社会的发展。"
}'

使用 Python requests 库测试：

import requests
import json

url = "http://127.0.0.1:8000/api/v1/similarity"
data = {
    "text1": "今天天气真好，适合出游。",
    "text2": "阳光明媚，是外出游玩的好日子。"
}
headers = {'Content-Type': 'application/json'}

response = requests.post(url, data=json.dumps(data), headers=headers)
print(response.json())
# 输出示例: {"similarity_score": 0.9213, "text1": "...", "text2": "...", "message": "success"}

现在，你的语义相似度服务就同时拥有了优雅的交互界面和标准的 API 接口。

5. 总结与扩展思路

5.1 我们完成了什么？

回顾一下这个实战教程，我们一步步构建了一个完整的、支持API调用的语义相似度微服务：

1. 环境搭建：准备好了Python环境和所有必要的依赖库。
2. 核心实现：成功加载了强大的中文语义理解模型 StructBERT，并编写了核心的相似度计算函数。
3. 前端交互：利用 Streamlit 快速构建了一个极具中国水墨美学风格的交互式Web应用，让技术有了温度。
4. 服务封装：进一步使用 FastAPI 将核心功能封装成 RESTful API，使其可以被其他应用程序轻松集成。

这个项目麻雀虽小，五脏俱全。它演示了从模型选择、本地部署、前端展示到服务化封装的全流程。

5.2 下一步可以做什么？

如果你对这个项目感兴趣，这里有几个可以继续深入的方向：

• 性能优化：当前API是同步的。对于高并发场景，可以考虑使用异步框架（如 async/await）或任务队列来提升吞吐量。
• 功能增强：实现批量相似度计算。修改API，使其能接收一个文本和一个文本列表，返回一组相似度分数。
• 部署上线：将服务部署到云服务器或容器平台（如 Docker）。你可以编写一个 Dockerfile，将环境、代码和模型打包成一个镜像，实现一键部署。
• 前端美化：进一步优化Streamlit界面的细节，比如增加动画效果、更丰富的解读文案、历史记录功能等。
• 模型微调：如果你有特定领域（如法律、医疗、金融）的文本数据，可以用它们来微调StructBERT模型，让它在你的专业领域表现更精准。

技术不仅是冰冷的代码，也可以是文化的载体。希望这个融合了传统美学与现代AI的项目，能为你带来一些启发，也为你解决实际的文本处理问题提供一个有力的工具。

---

获取更多AI镜像

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