# How to Customize or Swap Sentiment Analysis Models in InsightEngine

> Easily customize or swap sentiment analysis models in InsightEngine. Modify the model_name variable or replace the global instance for full control. Explore the bettafish repository for details.

- Repository: [BaiFu/bettafish](https://github.com/666ghj/bettafish)
- Tags: how-to-guide
- Published: 2026-02-23

---

**You can swap sentiment analysis models in InsightEngine by modifying the `model_name` variable in [`InsightEngine/tools/sentiment_analyzer.py`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/InsightEngine/tools/sentiment_analyzer.py) (around line 86) and modify the `model_name` variable:

```python

# 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:

```python
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`](https://github.com/666ghj/bettafish/blob/main/InsightEngine/tools/sentiment_analyzer.py):

```python
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:

```python

# 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`](https://github.com/666ghj/bettafish/blob/main/InsightEngine/tools/sentiment_analyzer.py):

```python
from .custom_sentiment import ExternalAPISentimentAnalyzer

# Replace the default instance

multilingual_sentiment_analyzer = ExternalAPISentimentAnalyzer()

```

All downstream code in [`InsightEngine/agent.py`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/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.