StructBERT 中文相似度服务部署与故障排查指南

日志定位技巧

日志是排查问题的核心依据。

日志位置

主要日志文件位于 /root/nlp_structbert_project/logs/ 下，包括 startup.log 和 service.log。

常用命令

• 实时查看：tail -f logs/startup.log
• 筛选错误：grep -i error logs/startup.log
• 清空重试：必要时清空日志文件重现问题，便于捕捉新产生的错误。

典型错误处理

• 端口被占用：使用 lsof -i :5000 查找进程并停止，或修改 app.py 中的端口号。
• 内存不足：若日志中出现 Killed，检查系统内存 (free -h)，考虑关闭其他服务或增加 Swap。
• 依赖缺失：出现 ModuleNotFoundError 时，激活虚拟环境并安装缺失包，如 pip install flask。
• 模型加载失败：检查模型文件是否存在，确保安装了必要的依赖库如 modelscope。

Supervisor 进程管理

使用 Supervisor 可确保服务稳定运行，实现开机自启和崩溃自动重启。

常用命令

supervisorctl status nlp_structbert
supervisorctl restart nlp_structbert
supervisorctl tail -f nlp_structbert

配置文件通常位于 /etc/supervisor/conf.d/nlp_structbert.conf，关键配置项 autostart=true 和 autorestart=true 保证了服务的持久性。

Web 界面使用与 API 调用

服务正常运行后，可通过 Web 界面进行单句或批量相似度计算。分数范围 0-1，越高表示语义越接近。

API 集成示例

若需在程序中调用，可使用 Python 客户端封装请求逻辑：

import requests

class StructBERTClient:
    def __init__(self, base_url="http://127.0.0.1:5000"):
        self.base_url = base_url

    def similarity(self, sentence1, sentence2):
        url = f"{self.base_url}/similarity"
        data = {"sentence1": sentence1, "sentence2": sentence2}
        try:
            response = requests.post(url, json=data, timeout=10)
            return response.json()["similarity"]
        except Exception as e:
            print(f"计算失败：{e}")
            return None

    def batch_similarity(self, source, targets):
        url = f"{self.base_url}/batch_similarity"
        data = {"source": source, "targets": targets}
        try:
            response = requests.post(url, json=data, timeout=10)
            results = response.json()["results"]
            return sorted(results, key=lambda x: x["similarity"], reverse=True)
        except Exception as e:
            print(f"批量计算失败：{e}")
            return []

实战应用场景

智能客服匹配

将用户问题与知识库进行批量比对，设定阈值（如 0.7）自动推荐最佳答案。

文章去重检测

对比新内容与已有文章库，识别语义重复内容，辅助内容审核。

内容推荐引擎

基于用户阅读历史，计算与候选内容的相似度，生成个性化推荐列表。

性能优化建议

批量处理

避免循环中逐个请求，优先使用批量接口减少网络开销。

结果缓存

对于重复查询，利用哈希键值对缓存计算结果，提升响应速度。

长文本处理

针对长文本，可先分块计算再取平均值，注意修复分块逻辑中的语法错误，确保文本正确拼接。

故障排查总结

遇到问题时，保持冷静并按步骤排查：

1. 确认进程存活：ps aux | grep python
2. 测试本地连接：curl http://127.0.0.1:5000/health
3. 分析日志报错：tail -f logs/startup.log
4. 检查网络配置：防火墙、绑定地址、端口占用

大部分问题可通过上述步骤定位。若仍无法解决，请重点检查服务是否真正启动以及依赖环境是否完整。