How to Customize or Swap Sentiment Analysis Models in InsightEngine

You can swap sentiment analysis models in InsightEngine by modifying the model_name variable in InsightEngine/tools/sentiment_analyzer.py or replacing the global multilingual_sentiment_analyzer instance with a custom class that implements the same interface.

The InsightEngine repository (666ghj/bettafish) implements a plug-in style sentiment analysis component that allows you to customize or swap sentiment analysis models without rewriting downstream orchestration logic. Whether you need to fine-tune the default multilingual model or replace it with an external API, the architecture decouples the model implementation from the search and reflection loops.

Understanding the Sentiment Analysis Architecture

The sentiment analysis system in InsightEngine uses a global instance pattern centered on the WeiboMultilingualSentimentAnalyzer class.

Key components include:

• WeiboMultilingualSentimentAnalyzer (in InsightEngine/tools/sentiment_analyzer.py): Wraps a Hugging Face AutoModelForSequenceClassification model, handles tokenization, preprocessing, and returns structured SentimentResult objects.
• multilingual_sentiment_analyzer: A globally accessible instance initialized lazily when the engine starts. All downstream components reference this singleton.
• Public API helpers: enable_sentiment_analysis(), disable_sentiment_analysis(), and analyze_sentiment() provide a thin interface for the rest of the system, including DeepSearchAgent in InsightEngine/agent.py.

When initialize() is called, the wrapper checks the SENTIMENT_ANALYSIS_ENABLED flag (default True) and verifies PyTorch and transformers availability. If the model is not present locally at SentimentAnalysisModel/WeiboMultilingualSentiment/model, it automatically downloads tabularisai/multilingual-sentiment-analysis from Hugging Face.

Swapping the Default Hugging Face Model

To replace the default model with a different Hugging Face checkpoint or a locally trained model, follow these steps:

Step 1: Select a Compatible Sequence Classification Model

Choose a model that outputs logits with shape [batch, N] where N matches your desired sentiment levels. The default wrapper expects five classes (very negative, negative, neutral, positive, very positive), but you can adapt the label mapping for different taxonomies.

Step 2: Update the Model Identifier

Locate the initialization code in InsightEngine/tools/sentiment_analyzer.py (around line 86) and modify the model_name variable:

# Original configuration

# model_name = "tabularisai/multilingual-sentiment-analysis"

# Updated to use a custom Hugging Face model

model_name = "myorg/finetuned-sentiment-zh-en"

# Or load from a local path

local_model_path = os.path.join(weibo_sentiment_path, "my_custom_model")
self.tokenizer = AutoTokenizer.from_pretrained(local_model_path)
self.model = AutoModelForSequenceClassification.from_pretrained(local_model_path)

Step 3: Adjust the Sentiment Label Mapping

If your new model uses a different class taxonomy, update the sentiment_map dictionary in the WeiboMultilingualSentimentAnalyzer.__init__ method:

self.sentiment_map = {
    0: "极度负面",      # very negative

    1: "负面",          # negative

    2: "中性",          # neutral

    3: "正面",          # positive

    4: "极度正面",      # very positive

}

Ensure the integer keys align with your model's output indices. After restarting the engine, initialize() will load the new checkpoint on the first analysis call.

Runtime Control: Enabling and Disabling Sentiment Analysis

You can toggle sentiment analysis without restarting the service using the helper functions exposed in InsightEngine/tools/sentiment_analyzer.py:

from InsightEngine.tools import disable_sentiment_analysis, enable_sentiment_analysis, analyze_sentiment

# Disable for lightweight debugging or when GPU resources are constrained

disable_sentiment_analysis(reason="Running in lightweight mode", drop_state=True)

# Analysis calls now return bypass warnings

result = analyze_sentiment("这个产品真不错！")
print(result["warning"])  # → "情感分析功能不可用，已直接返回原始文本"

# Re-enable when needed

enable_sentiment_analysis()

# The next call triggers model initialization if not already loaded

For permanent disabling, set the constant SENTIMENT_ANALYSIS_ENABLED = False at line 31 in the source file. The DeepSearchAgent checks self.sentiment_analyzer.is_disabled before each analysis, ensuring safe runtime toggling.

Implementing a Custom Sentiment Analyzer

To integrate a completely different backend (such as an external REST API or a spaCy pipeline), create a class that implements the required interface:

# File: InsightEngine/tools/custom_sentiment.py

import requests
from dataclasses import dataclass
from typing import Dict, List

@dataclass
class SentimentResult:
    text: str
    sentiment_label: str
    confidence: float
    probability_distribution: Dict[str, float]
    success: bool = True
    error_message: str | None = None
    analysis_performed: bool = True

class ExternalAPISentimentAnalyzer:
    def __init__(self):
        self.api_endpoint = "https://api.example.com/sentiment/v1"
        self.is_initialized = True
        self.is_disabled = False
        
    def initialize(self) -> bool:
        """Optional health check for external service availability."""
        try:
            r = requests.get(f"{self.api_endpoint}/health")
            return r.status_code == 200
        except Exception:
            self.is_disabled = True
            return False
            
    def analyze_single_text(self, text: str) -> SentimentResult:
        """Core method called by the engine for single text analysis."""
        resp = requests.post(
            f"{self.api_endpoint}/predict", 
            json={"text": text}
        )
        if resp.status_code != 200:
            return SentimentResult(
                text=text,
                sentiment_label="分析失败",
                confidence=0.0,
                probability_distribution={},
                success=False,
                error_message="API error",
                analysis_performed=False,
            )
        data = resp.json()
        return SentimentResult(
            text=text,
            sentiment_label=data["label"],
            confidence=data["confidence"],
            probability_distribution=data.get("probabilities", {}),
        )
        
    def analyze_batch(self, texts: List[str], show_progress: bool = True):
        """Batch processing wrapper (implementation omitted for brevity)."""
        return [self.analyze_single_text(t) for t in texts]

After implementing your custom class, swap the global instance in InsightEngine/tools/sentiment_analyzer.py:

from .custom_sentiment import ExternalAPISentimentAnalyzer

# Replace the default instance

multilingual_sentiment_analyzer = ExternalAPISentimentAnalyzer()

All downstream code in InsightEngine/agent.py and other modules will automatically use your custom implementation without requiring additional changes.

Summary

• Architecture: InsightEngine uses a singleton multilingual_sentiment_analyzer (instance of WeiboMultilingualSentimentAnalyzer) defined in InsightEngine/tools/sentiment_analyzer.py.
• Model Swapping: Change the model_name variable or point to a local path in the wrapper's initialization code, then align the sentiment_map dictionary with your model's output classes.
• Runtime Control: Use disable_sentiment_analysis() and enable_sentiment_analysis() to toggle functionality without restarting, or set SENTIMENT_ANALYSIS_ENABLED = False for permanent disabling.
• Custom Backends: Implement a class with initialize(), analyze_single_text(), and analyze_batch() methods, then replace the global instance to integrate external APIs or alternative libraries.

Frequently Asked Questions

What file contains the sentiment analysis model configuration?

The core configuration and model loading logic resides in InsightEngine/tools/sentiment_analyzer.py. This file contains the WeiboMultilingualSentimentAnalyzer class, the global multilingual_sentiment_analyzer instance, and the helper functions used throughout the engine.

Can I use a local model instead of downloading from Hugging Face?

Yes. Modify the initialization code in InsightEngine/tools/sentiment_analyzer.py to point AutoModelForSequenceClassification.from_pretrained() to a local directory under SentimentAnalysisModel/WeiboMultilingualSentiment/model or any absolute path on your system. Ensure the directory contains valid PyTorch model weights and a tokenizer configuration.

How many sentiment classes does the default implementation support?

The default WeiboMultilingualSentimentAnalyzer expects five sentiment classes indexed 0 through 4: very negative, negative, neutral, positive, and very positive. If your replacement model uses a different number of classes, you must update the sentiment_map dictionary and any downstream logic that interprets probability distributions.

Will disabling sentiment analysis improve performance?

Yes. When you call disable_sentiment_analysis() or set SENTIMENT_ANALYSIS_ENABLED = False, the DeepSearchAgent skips all model inference calls, reducing memory usage and eliminating the GPU/CPU overhead associated with transformer model execution. This is useful for lightweight deployments or when running on hardware without CUDA support.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}