Customer Sentiment Analysis

客户评论分析器🤖

一个智能Python应用程序，使用 LangChain, 拥抱脸LLMs，以及 模型上下文协议（MCP） 自动将客户评论分为类别（旅行、住宿、食物）并分析他们的情绪（积极、消极、中立）。

特性✨

核心功能

• 类别分类：自动将客户评论分类为：

- ✈️ 旅行（航班、航空公司、交通） - 🏨 住宿（酒店、住宿、住宿） - 🍽️ 食物（餐厅、餐饮、餐点）

• 情感分析：确定注释是否为：

- 😊 积极的 - 😞 负面的 - 😐 中性

• 批处理：通过进度跟踪一次分析多条评论

• 统计仪表板：显示类别和情绪分布的交互式图表

• 导出功能：将分析结果下载为CSV文件

• 分析历史：使用时间戳跟踪所有以前的分析

技术特性

• 模型上下文协议（MCP）：用于生产部署的服务器客户端架构
• 外部提示模板：易于定制的提示存储在单独的文件中
• 网络界面：与MCP集成的Streamlit应用程序
• 由AI驱动：通过Hugging Face使用Meta Llama 3.2模型
• 同步MCP客户端：可靠的基于子流程的沟通

建筑🏗️

应用程序使用 模型上下文协议（MCP） 架构：

┌─────────────────┐         MCP Protocol        ┌──────────────────┐
│                 │◄────────────────────────────►│                  │
│  Streamlit App  │    JSON-RPC over stdio       │   MCP Server     │
│    (app.py)     │                              │  (mcp_server.py) │
└─────────────────┘                              └──────────────────┘
        │                                                 │
        │                                                 ▼
        │                                         ┌──────────────────┐
        │                                         │  LangChain +     │
        └─────────────────────────────────────────│  Hugging Face    │
                  via mcp_client.py               │  Analysis Logic  │
                                                  └──────────────────┘

看 ARCHITECTURE.md 获取详细的架构文档。

先决条件📋

• Python 3.8或更高版本
• 拥抱脸账户和API代币(在这里买一个)
• API调用的Internet连接

安装🚀

1. 克隆或导航到项目目录:

   cd "c:\Abhishek\Purdue-Python\Customer Sentiment Analysis"

1. 安装所需的软件包:

   pip install -r requirements.txt

这将安装所有依赖项，包括：

- LangChain与拥抱脸的融合 - Streamlit用于web界面 - 服务架构的模型上下文协议（MCP） - 所有必需的AI/ML库

1. 设置你的拥抱脸API代币:

从以下位置获取您的令牌：https://huggingface.co/settings/tokens

选项A：设置为环境变量（推荐）：

   $env:HUGGINGFACEHUB_API_TOKEN='your_token_here'

选项B：出现提示时，在web界面中输入令牌

用法💻

Web应用程序（推荐）🌐

启动启用MCP的Streamlit web界面：

streamlit run app.py

应用程序将自动：

• 在后台启动MCP服务器
• 将客户端连接到服务器
• 初始化AI模型

web界面提供：

• 令牌输入：输入您的拥抱脸令牌进行连接
• 单项评论分析：一次分析一条评论
• 批次分析：同时处理多条评论
• 加载样本数据：每个类别的预加载示例
• 视觉统计：结果图表
• 导出结果：以CSV格式下载分析
• 分析历史：跟踪您之前的所有分析

命令行用法

运行独立分析器：

C:/Python313/python.exe customer_comment_analyzer.py

测试MCP服务器：

C:/Python313/python.exe mcp/mcp_server.py

测试MCP客户端：

C:/Python313/python.exe mcp/mcp_client.py

查看示例注释：

C:/Python313/python.exe sample_comments.py

程序化使用

直接使用分析仪：

from customer_comment_analyzer import CustomerCommentAnalyzer

# Initialize the analyzer
analyzer = CustomerCommentAnalyzer(hf_token="your_token_here")

# Analyze a single comment
result = analyzer.analyze_comment("The flight was delayed but staff was helpful")
print(result)
# Output: {'comment': '...', 'category': 'AIRLINE', 'sentiment': 'NEUTRAL'}

# Analyze multiple comments
comments = [
    "Hotel room was amazing!",
    "Food was terrible",
    "Flight delayed again"
]
results = analyzer.analyze_batch(comments)
analyzer.print_results(results)

使用MCP客户端：

# Add mcp directory to path if needed
import sys
from pathlib import Path
sys.path.insert(0, str(Path.cwd() / "mcp"))

from mcp.mcp_client import SyncCommentAnalyzerClient

# Using context manager (recommended)
with SyncCommentAnalyzerClient() as client:
    result = client.analyze_comment("Great service!")
    print(result)
    
    # Batch analysis
    results = client.analyze_batch(["Comment 1", "Comment 2"])
    
    # Get statistics
    stats = client.get_statistics(results)
    print(stats)

使用示例注释：

from sample_comments import get_comments_by_category

# Get specific category comments
airline_comments = get_comments_by_category('airline')
hotel_comments = get_comments_by_category('hotel')
food_comments = get_comments_by_category('food')
mixed_comments = get_comments_by_category('mixed')
all_comments = get_comments_by_category('all')

项目结构📁

Langchain/
│
├── mcp/                            # Model Context Protocol implementation
│   ├── mcp_server.py               # MCP server exposing AI tools
│   ├── mcp_client.py               # MCP client library
│   ├── app_mcp.py                  # Streamlit app using MCP
│   └── README.md                   # MCP architecture documentation
│
├── prompts/                        # Prompt template files
│   ├── classification_prompt.txt   # Category classification template
│   ├── sentiment_prompt.txt        # Sentiment analysis template
│   └── README.md                   # Prompt customization guide
│
├── app.py                          # Streamlit web app (direct integration)
├── customer_comment_analyzer.py    # Core AI analysis logic
├── sample_comments.py              # Sample customer comments
├── example_usage.py                # Usage examples
├── requirements.txt                # Python dependencies
└── README.md                       # This file

运作原理🔧

1. LangChain集成：使用LangChain的 HuggingFaceEndpoint 连接到Hugging Face模型
2. 外部提示模板：提示存储在单独的文本文件中，便于自定义
3. 模型上下文协议：用于基于服务的部署的可选MCP架构
4. 链状结构：用于分类和情感分析的单独链
5. 模型：使用Mistral-7B-Instruct-v0.2，一个强大的指令跟踪模型

架构选项

直接积分法 (app.py):

• 简单、单流程设计
• 直接调用分析器的函数
• 有利于开发和原型制作

MCP架构 (mcp/app_mcp.py + mcp/mcp_server.py):

• 客户端-服务器体系结构
• 标准化协议通信
• 更适合生产部署
• UI和AI的独立扩展
• 多客户端支持
• 看 mcp/README.md 有关完整详细信息

提示模板

所有提示模板都外部化到 prompts/ 目录，无需更改代码即可轻松修改：

可用模板：

• classification_prompt.txt -类别分类说明
• sentiment_prompt.txt -情绪分析说明
• README.md -带示例的完整定制指南

优点：

• 编辑提示而不触摸代码
• 用于快速更改的版本控制
• 轻松进行不同提示的A/B测试
• 无需重新部署即可快速更新

模板结构示例：

Classify the following customer comment into ONE of these categories: 
AIRLINE, HOTEL, or FOOD.
Only respond with one of these three words in uppercase.

Customer comment: {comment}

Category:

看 prompts/README.md 详细的定制示例包括：

• 添加新类别
• 实施少镜头学习
• 更改情绪粒度
• 自定义输出格式

输出示例📊

命令行输出：

================================================================================
CUSTOMER COMMENT ANALYSIS RESULTS
================================================================================

--- Comment 1 ---
Text: The flight was delayed by 3 hours and the staff was very rude.
Category: AIRLINE
Sentiment: NEGATIVE

--- Comment 2 ---
Text: Hotel room was clean and spacious. The breakfast buffet was amazing!
Category: HOTEL
Sentiment: POSITIVE

--- Comment 3 ---
Text: The pasta was undercooked and the service was slow.
Category: FOOD
Sentiment: NEGATIVE

================================================================================

SUMMARY STATISTICS
--------------------------------------------------------------------------------

Category Distribution:
  AIRLINE: 3 (33.3%)
  FOOD: 3 (33.3%)
  HOTEL: 3 (33.3%)

Sentiment Distribution:
  NEGATIVE: 4 (44.4%)
  NEUTRAL: 2 (22.2%)
  POSITIVE: 3 (33.3%)
================================================================================

定制🎨

自定义提示模板

在中编辑模板文件 prompts/ 要修改行为的目录：

示例：添加更多类别 (prompts/classification_prompt.txt):

Classify the following customer comment into ONE of these categories: 
AIRLINE, HOTEL, FOOD, CAR_RENTAL, or TOUR_PACKAGE.

Customer comment: {comment}

Category:

示例：添加情感粒度 (prompts/sentiment_prompt.txt):

Analyze the sentiment of the following customer comment.
Classify it as: VERY_POSITIVE, POSITIVE, NEUTRAL, NEGATIVE, or VERY_NEGATIVE.

Customer comment: {comment}

Sentiment:

看 prompts/README.md 了解更多定制示例和最佳实践。

使用不同的模型

您可以通过修改以下内容来更改“拥抱脸”模型 repo_id 在 CustomerCommentAnalyzer.__init__():

self.llm = HuggingFaceEndpoint(
    repo_id="google/flan-t5-large",  # Change to any compatible model
    temperature=0.3,
    max_new_tokens=512
)

流行的替代方案：

• google/flan-t5-large -更小更快
• HuggingFaceH4/zephyr-7b-beta -有助于指导
• tiiuae/falcon-7b-instruct -高效的替代方案

使用自定义提示目录

您可以为提示模板指定自定义位置：

analyzer = CustomerCommentAnalyzer(
    hf_token="your_token",
    prompts_dir="path/to/custom/prompts"
)

故障排除🔍

常见问题

“未找到拥抱脸令牌”

• 设置API令牌： $env:HUGGINGFACEHUB_API_TOKEN='your_token_here'
• 或者在Streamlit侧栏中输入
• 从以下位置获取令牌：https://huggingface.co/settings/tokens

模型加载缓慢

• 首次加载需要几分钟（下载模型）
• 后续的运行速度要快得多
• 考虑使用较小的模型以加快加载速度

“超出费率限制”

• 免费等级有请求限制
• 在大批量之间等待几分钟
• 升级到Hugging Face Pro以获得更高的限制
• 考虑生产中的局部模型推理

MCP连接错误

• 启动应用程序前，确保设置了环境变量
• 检查MCP文件是否在 mcp/ 目录
• 验证Python是否可以从mcp目录导入
• 尝试直接版本(app.py)如果MCP问题持续存在
• 检查控制台输出以获取详细的错误消息

“找不到提示模板文件”

• 确保 prompts/ 目录存在
• 检查一下 .txt 文件存在
• 验证文件路径是否正确

令牌长度错误

• 减少 max_new_tokens 参数在 customer_comment_analyzer.py
• 使用较短的评论
• 尝试使用具有更大上下文窗口的不同模型

性能提示

• 对多条评论使用批量分析（更高效）
• 缓存结果以避免重新分析相同的评论
• 考虑单独运行MCP服务器以获得更好的性能
• 使用GPU（如果可用）（需要CUDA设置）

API费率限制⚠️

免费拥抱脸API有价格限制：

• 注意请求的数量
• 考虑对大规模应用程序使用局部模型推理
• 升级到Hugging Face Pro以获得更高的限制

未来的增强功能🚀

潜在的改进和功能：

• \[ \] 本地模型支持 -在没有API调用的情况下本地运行模型
• \[ \] 其他导出格式 -JSON、Excel、PDF报告
• \[ \] 多语言支持 -分析多种语言的评论
• \[ \] 自定义类别 -用户定义的分类类别
• \[ \] 高级分析 -词云、趋势分析、关键短语提取
• \[ \] 实时处理 -WebSocket支持实时评论流
• \[ \] 数据库集成 -将结果存储在PostgreSQL/MongoDB中
• \[ \] REST API -用于外部集成的HTTP API端点
• \[ \] 认证 -用户帐户和API密钥管理
• \[ \] 微调 -针对特定领域数据的自定义模型训练
• \[ \] 置信度得分 -预测的概率分数
• \[ \] A/B测试 -比较不同的提示和型号
• \[ \] Docker支持 -集装箱化部署
• \[ \] 云部署 -AWS/Azure/GCP部署指南

使用的技术🛠️

核心技术

• Python 3.13 -程序设计语言
• LangChain -LLM编排和链管理
• 拥抱脸变换器 -人工智能模型访问和管理
• Mistral-7B-说明书-0.2 -指令遵循语言模型

Web和UI

• 溪流 -交互式web应用程序框架
• 熊猫 -数据操作和CSV导出

模型上下文协议

• MCP-SDK -模型上下文协议实现
• httpx -用于异步操作的HTTP客户端
• 派丹蒂克 -数据验证

AI/ML库

• 火炬（PyTorch） -深度学习框架
• 句子 -标记化
• 加速 -模型优化
• 拥抱面中心 -模型存储库访问

快速入门指南🚀

1.获取您的拥抱脸令牌

访问https://huggingface.co/settings/tokens并创建免费令牌

2.设置环境变量

$env:HUGGINGFACEHUB_API_TOKEN='your_token_here'

3.选择您的界面

Web界面（最简单）：

C:/Python313/python.exe -m streamlit run app.py

MCP版本（生产）：

C:/Python313/python.exe -m streamlit run mcp/app_mcp.py

命令行：

C:/Python313/python.exe customer_comment_analyzer.py

4.开始分析！

• 在web界面中输入评论，或
• 在您自己的脚本中使用Python API

文档📚

• README.md （此文件）-主要文档和设置指南
• mcp/README.md -模型上下文协议架构详细信息
• 提示/README.md -提示模板定制指南
• 代码注释-所有Python文件中的内联文档

项目特性概述

许可证📄

这个项目是为了教育目的而创建的。

贡献🤝

欢迎投稿！以下是您可以提供帮助的方式：

1. 报告Bug -打开一个包含详细信息的问题
2. 建议功能 -分享您的改进想法
3. 改进文档 -帮助使文档更清晰
4. 提交PR -修复错误或添加功能
5. 分享反馈 -让我们知道您是如何使用它的

支持💬

对于问题或疑问：

1. 检查 故障排除 以上章节
2. 审查 mcp/README.md 针对MCP特定问题
3. 检查 提示/README.md 用于快速定制
4. 审查 LangChain文档
5. 访问 拥抱脸文档
6. 检查 模型上下文协议文档

致谢🙏

采用令人惊叹的开源技术构建：

• LangChain团队为优秀的编排框架
• 拥抱人脸，使人工智能模型访问民主化
• Mistral AI用于强大的指令跟踪模型
• Streamlit用于直观的web框架
• 标准化模型上下文协议团队

______________________________________________________________________

由以下材料制成❤️ 使用LangChain、Hugging Face、模型上下文协议和Streamlit

*快乐分析！ 🎉*