dgx-spark-playbooks/nvidia/txt2kg/assets/deploy/services/gpu-viz/README.md

GPU Graph Visualization Services

🚀 Overview

This directory contains optional GPU-accelerated graph visualization services that run separately from the main txt2kg application. These services provide advanced visualization capabilities for large-scale graphs.

Note: These services are optional and not included in the default docker-compose configurations. They must be run separately.

📦 Available Services

1. Unified GPU Service (unified_gpu_service.py)

Combines PyGraphistry Cloud and Local GPU (cuGraph) processing into a single FastAPI service.

Processing Modes:

Mode	Description	Requirements
PyGraphistry Cloud	Interactive GPU embeds in browser	API credentials
Local GPU (cuGraph)	Full GPU processing on your hardware	NVIDIA GPU + cuGraph
Local CPU	NetworkX fallback processing	None

2. Remote GPU Rendering Service (remote_gpu_rendering_service.py)

Provides GPU-accelerated graph layout and rendering with iframe-embeddable visualizations.

3. Local GPU Service (local_gpu_viz_service.py)

Local GPU processing service with WebSocket support for real-time updates.

🛠️ Setup

Prerequisites

• NVIDIA GPU with CUDA support (for GPU modes)
• RAPIDS cuGraph (for local GPU processing)
• PyGraphistry account (for cloud mode)

Installation

# Install dependencies
pip install -r deploy/services/gpu-viz/requirements.txt

# For remote WebGPU service
pip install -r deploy/services/gpu-viz/requirements-remote-webgpu.txt

Running Services

Unified GPU Service

cd deploy/services/gpu-viz
python unified_gpu_service.py

Service runs on: http://localhost:8080

Remote GPU Rendering Service

cd deploy/services/gpu-viz
python remote_gpu_rendering_service.py

Service runs on: http://localhost:8082

Using Startup Script

cd deploy/services/gpu-viz
./start_remote_gpu_services.sh

📡 API Usage

Process Graph with Mode Selection

curl -X POST http://localhost:8080/api/visualize \
  -H "Content-Type: application/json" \
  -d '{
    "graph_data": {
      "nodes": [{"id": "1", "name": "Node 1"}, {"id": "2", "name": "Node 2"}],
      "links": [{"source": "1", "target": "2", "name": "edge_1_2"}]
    },
    "processing_mode": "local_gpu",
    "layout_algorithm": "force_atlas2",
    "clustering_algorithm": "leiden",
    "compute_centrality": true
  }'

Check Available Capabilities

curl http://localhost:8080/api/capabilities

Response:

{
  "processing_modes": {
    "pygraphistry_cloud": {"available": true, "description": "..."},
    "local_gpu": {"available": true, "description": "..."},
    "local_cpu": {"available": true, "description": "..."}
  },
  "has_rapids": true,
  "gpu_available": true
}

🎯 Frontend Integration

The txt2kg frontend includes built-in components for GPU visualization:

• UnifiedGPUViewer: Connects to unified GPU service
• PyGraphistryViewer: Direct PyGraphistry cloud integration
• ForceGraphWrapper: Three.js WebGPU visualization (default)

Using GPU Services in Frontend

The frontend has API routes that can connect to these services:

• /api/pygraphistry/*: PyGraphistry integration
• /api/unified-gpu/*: Unified GPU service integration

To use these services, ensure they are running separately and configure the frontend environment variables accordingly.

Mode-Specific Processing

// PyGraphistry Cloud mode
const response = await fetch('/api/unified-gpu/visualize', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    graph_data: { nodes, links },
    processing_mode: 'pygraphistry_cloud',
    layout_type: 'force',
    clustering: true,
    gpu_acceleration: true
  })
})

// Local GPU mode  
const response = await fetch('/api/unified-gpu/visualize', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    graph_data: { nodes, links },
    processing_mode: 'local_gpu',
    layout_algorithm: 'force_atlas2',
    clustering_algorithm: 'leiden',
    compute_centrality: true
  })
})

🔧 Configuration Options

PyGraphistry Cloud Mode

• layout_type: "force", "circular", "hierarchical"
• gpu_acceleration: true/false
• clustering: true/false

Local GPU Mode

• layout_algorithm: "force_atlas2", "spectral", "fruchterman_reingold"
• clustering_algorithm: "leiden", "louvain", "spectral"
• compute_centrality: true/false

Local CPU Mode

• Basic processing with NetworkX fallback
• No additional configuration needed

📊 Response Format

{
  "processed_nodes": [...],
  "processed_edges": [...],
  "processing_mode": "local_gpu",
  "embed_url": "https://hub.graphistry.com/...", // Only for cloud mode
  "layout_positions": {...}, // Only for local GPU mode
  "clusters": {...},
  "centrality": {...},
  "stats": {
    "node_count": 1000,
    "edge_count": 5000,
    "gpu_accelerated": true,
    "layout_computed": true,
    "clusters_computed": true
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

🚀 Benefits of Unified Approach

✅ Advantages

• Single service - One port, one deployment
• Mode switching - Choose best processing per graph
• Fallback handling - Graceful degradation if GPU unavailable
• Consistent API - Same interface for all modes
• Better testing - Easy comparison between modes

🎯 Use Cases

• PyGraphistry Cloud: Sharing visualizations, demos, production embeds
• Local GPU: Private data, large-scale processing, custom algorithms
• Local CPU: Development, testing, small graphs

🐛 Troubleshooting

GPU Not Detected

# Check GPU availability
nvidia-smi

# Check RAPIDS installation
python -c "import cudf, cugraph; print('RAPIDS OK')"

PyGraphistry Credentials

# Verify credentials are set
echo $GRAPHISTRY_PERSONAL_KEY
echo $GRAPHISTRY_SECRET_KEY

# Test connection
python -c "import graphistry; graphistry.register(personal_key_id='$GRAPHISTRY_PERSONAL_KEY', personal_key_secret='$GRAPHISTRY_SECRET_KEY'); print('PyGraphistry OK')"

Service Health

curl http://localhost:8080/api/health

📈 Performance Tips

1. Large graphs (>100k nodes): Use local_gpu mode
2. Sharing/demos: Use pygraphistry_cloud mode
3. Development: Use local_cpu mode for speed
4. Mixed workloads: Switch modes dynamically based on graph size