Hugging Face's logo

Spaces:
Lyon28
/
AI-Character-Chat
Running

App Files Community
AI-Character-Chat / README.md
Lyon28's picture
Lyon28
Update README.md
8bf72d7 verified
preview code
|
raw
history blame contribute delete
7.87 kB
metadata
title: AI Character Chat
emoji: 🔥
colorFrom: green
colorTo: green
sdk: docker
pinned: false

Character AI Chat - CPU Optimized Backend

🎭 Advanced Character AI Chat System dengan dukungan 11 model AI yang dioptimalkan untuk CPU, dilengkapi dengan sistem roleplay canggih, memori percakapan, dan kecerdasan emosional.

✨ Fitur Utama

🧠 Multi-Model AI Support

  • 11 Model AI yang dioptimalkan untuk CPU
  • Mendukung berbagai jenis task: Text Generation, Classification, Text2Text
  • Auto-loading dengan lazy initialization untuk performa optimal

🎭 Advanced Roleplay System

  • Conversation Memory - Mengingat percakapan sebelumnya
  • Dynamic Personality - Karakter yang berkembang seiring waktu
  • Emotional Intelligence - Mendeteksi dan merespons emosi user
  • Character Development - Belajar preferensi dan adaptasi gaya bicara
  • Roleplay Actions - Aksi fisik dan emosional yang kontekstual
  • Relationship Tracking - Level hubungan yang berkembang

🌟 Enhanced Features

  • Situational Context - Respons disesuaikan dengan situasi dan lokasi
  • Indonesian Language Optimized - Dioptimalkan untuk bahasa Indonesia
  • Session Management - Multiple session dengan memori terpisah
  • Real-time Processing - Response time tracking
  • Fallback System - Sistem backup untuk handling error

🚀 Model yang Didukung

⚡ Priority 1 (Ultra Fast)

  • DistilGPT-2 - Text generation ringan dan cepat
  • GPT-2 Tinny - Versi kompak GPT-2
  • BERT Tinny - Text classification ringan
  • DistilBERT - Classification model yang efisien

🔥 Priority 2 (Balanced)

  • ALBERT Base - Advanced text understanding
  • ELECTRA Small - Efficient pre-training model
  • T5 Small - Text-to-text generation
  • GPT-2 Standard - Standard GPT-2 model

💪 Priority 3 (Advanced)

  • Tinny Llama - Compact large language model
  • Pythia - Research-grade model
  • GPT-Neo - Open-source GPT alternative

📋 Persyaratan Sistem

Software Requirements 

Python 3.8+
FastAPI
Transformers
PyTorch (CPU version)
Uvicorn

Hardware Requirements

  • CPU: Multi-core processor (minimum 4 cores recommended)
  • RAM: 8GB minimum, 16GB recommended
  • Storage: 10GB free space untuk model cache
  • Platform: Windows, macOS, Linux

🛠️ Instalasi

1. Clone Repository 

git clone <repository-url>
cd character-ai-chat

2. Install Dependencies 

pip install -r requirements.txt

3. Setup Environment 

# Optional: Set cache directory
export HF_HOME=/path/to/cache
export TRANSFORMERS_CACHE=/path/to/cache

4. Prepare Assets

Pastikan file berikut ada di root directory:

  • index.html - Frontend interface
  • avatar.png - Character avatar (optional)
  • background.png - Background image (optional)

5. Run Application 

python app.py

Aplikasi akan berjalan di: http://localhost:7860

🎮 Cara Penggunaan

Basic Chat 

import requests

response = requests.post("http://localhost:7860/chat", json={
    "message": "Hai, apa kabar?",
    "model": "distil-gpt-2",
    "char_name": "Sayang",
    "user_name": "Kamu",
    "situation": "Santai",
    "location": "Ruang tamu"
})

print(response.json()["response"])

Advanced Usage dengan Session 

# Chat dengan session tracking
response = requests.post("http://localhost:7860/chat", json={
    "message": "Aku sedang sedih hari ini",
    "model": "gpt-2",
    "char_name": "Luna",
    "user_name": "Alex",
    "situation": "Romantis",
    "location": "Taman",
    "session_id": "user_123"
})

Cek Memory Session 

# Lihat conversation memory
memory = requests.get("http://localhost:7860/memory/user_123")
print(memory.json())

# Lihat personality development
personality = requests.get("http://localhost:7860/personality/user_123")
print(personality.json())

🌐 API Endpoints

Core Endpoints

  • POST /chat - Main chat endpoint
  • GET /models - List available models
  • GET /health - Health check
  • GET /config - Configuration info

Enhanced Features

  • GET /memory/{session_id} - Get conversation memory
  • GET /personality/{session_id} - Get character personality
  • DELETE /session/{session_id} - Reset session data

Utility Endpoints

  • GET /verify-models - Verify all models loading
  • POST /inference - Alternative inference endpoint
  • GET /api - API documentation

🎨 Kustomisasi Karakter

Personality Traits

Karakter memiliki 5 trait utama yang dapat disesuaikan:

personality.traits = {
    "extraversion": 0.7,      # Seberapa ekstrovert (0-1)
    "agreeableness": 0.8,     # Seberapa mudah setuju (0-1)
    "conscientiousness": 0.6,  # Seberapa teliti (0-1)
    "neuroticism": 0.3,       # Seberapa cemas (0-1)
    "openness": 0.7          # Seberapa terbuka (0-1)
}

Speaking Styles

  • casual_friendly - Santai dan ramah
  • romantic_caring - Romantis dan perhatian
  • supportive_warm - Supportif dan hangat
  • playful_teasing - Main-main dan menggoda

Situasi yang Didukung

  • Santai - Obrolan santai sehari-hari
  • Romantis - Suasana romantis dan intim
  • Sedih - Memberikan dukungan emosional
  • Excited - Berbagi kegembiraan
  • Study - Membantu belajar
  • Gaming - Ngobrol tentang games

🔧 Optimisasi CPU

Memory Management 

# CPU thread optimization
torch.set_num_threads(2)
os.environ['OMP_NUM_THREADS'] = '2'
os.environ['MKL_NUM_THREADS'] = '2'

# Memory cleanup
gc.collect()

Model Loading Strategy

  • Lazy Loading - Model dimuat saat pertama kali digunakan
  • Shared Pipelines - Reuse pipeline untuk efisiensi
  • Cache Management - Automatic cache cleanup

📊 Performance Monitoring

Response Time Tracking

Setiap response dilengkapi dengan informasi performa:

{
    "response": "Hai! Apa kabar?",
    "processing_time": "450ms",
    "model": "DistilGPT-2 ⚡",
    "status": "success"
}

Memory Usage 

# Check memory usage
GET /health
{
    "loaded_models": 5,
    "memory_usage": "2.1GB",
    "optimization": "Character AI CPU-Tuned"
}

🐛 Troubleshooting

Common Issues

Model Loading Error

# Solution: Clear cache
rm -rf /tmp/.cache/huggingface

Out of Memory

# Reduce max_length
request.max_length = 100

# Use lighter models
model = "distil-gpt-2"  # instead of "gpt-neo"

Slow Response

# Use priority 1 models for faster response
recommended_models = ["distil-gpt-2", "gpt-2-tinny", "bert-tinny"]

Debug Mode 

# Run with debug logging
PYTHONPATH=. python -m uvicorn app:app --reload --log-level debug

🤝 Contributing

Development Setup 

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

# Code formatting
black app.py
flake8 app.py

Adding New Models

  1. Tambahkan model config di MODELS dictionary
  2. Test dengan /verify-models endpoint
  3. Update documentation

Adding New Features

  1. Extend appropriate class (ConversationMemory, CharacterPersonality, etc.)
  2. Add endpoint if needed
  3. Update API documentation

📄 License

MIT License - Lihat file LICENSE untuk detail lengkap.

🙏 Acknowledgments

  • Hugging Face Transformers - Model implementation
  • FastAPI - Web framework
  • PyTorch - Deep learning backend
  • Community Contributors - Bug reports and suggestions

📞 Support

📈 Stats

  • 11 AI Models supported
  • CPU Optimized for affordable hosting
  • Advanced Roleplay features
  • Indonesian Language optimized
  • Real-time Processing under 500ms average

Happy Chatting! 🎭✨