Create QUICKSTART.md

QUICKSTART.md

@@ -0,0 +1,287 @@
+# Helion-V2.0-Thinking Quickstart Guide
+
+Get started with Helion-V2.0-Thinking in minutes.
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install transformers torch accelerate pillow requests
+```
+
+### Full Installation (with all features)
+
+```bash
+pip install -r requirements.txt
+```
+
+### GPU Requirements
+
+- **Minimum**: 24GB VRAM (RTX 4090, A5000)
+- **Recommended**: 40GB+ VRAM (A100, H100)
+- **Quantized (8-bit)**: 16GB VRAM
+- **Quantized (4-bit)**: 12GB VRAM
+
+## Quick Examples
+
+### 1. Basic Text Generation
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "DeepXR/Helion-V2.0-Thinking"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    torch_dtype="auto",
+    device_map="auto"
+)
+
+prompt = "What is artificial intelligence?"
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+outputs = model.generate(**inputs, max_new_tokens=256)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+### 2. Image Understanding
+
+```python
+from transformers import AutoModelForCausalLM, AutoProcessor
+from PIL import Image
+
+processor = AutoProcessor.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    torch_dtype="auto",
+    device_map="auto"
+)
+
+image = Image.open("photo.jpg")
+prompt = "What is in this image?"
+inputs = processor(text=prompt, images=image, return_tensors="pt").to(model.device)
+outputs = model.generate(**inputs, max_new_tokens=256)
+print(processor.decode(outputs[0], skip_special_tokens=True))
+```
+
+### 3. Using the Inference Script
+
+```bash
+# Interactive chat mode
+python inference.py --interactive
+
+# With image analysis
+python inference.py --image photo.jpg --prompt "Describe this image"
+
+# Run demos
+python inference.py --demo
+
+# With quantization (saves memory)
+python inference.py --interactive --load-in-4bit
+```
+
+### 4. With Safety Wrapper
+
+```python
+from safety_wrapper import SafeHelionWrapper
+
+# Initialize with safety features
+wrapper = SafeHelionWrapper(
+    model_name="DeepXR/Helion-V2.0-Thinking",
+    enable_safety=True,
+    enable_rate_limiting=True
+)
+
+# Safe generation
+response = wrapper.generate(
+    prompt="Explain photosynthesis",
+    max_new_tokens=256
+)
+print(response)
+```
+
+### 5. Function Calling
+
+```python
+import json
+
+tools = [{
+    "name": "calculator",
+    "description": "Perform calculations",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "expression": {"type": "string"}
+        }
+    }
+}]
+
+prompt = f"""Available tools: {json.dumps(tools)}
+
+User: What is 125 * 48?
+Assistant (respond with JSON):"""
+
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+outputs = model.generate(**inputs, max_new_tokens=128, temperature=0.2)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+## Memory-Efficient Options
+
+### 8-bit Quantization
+
+```python
+from transformers import BitsAndBytesConfig
+
+quantization_config = BitsAndBytesConfig(load_in_8bit=True)
+
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    quantization_config=quantization_config,
+    device_map="auto"
+)
+```
+
+### 4-bit Quantization
+
+```python
+quantization_config = BitsAndBytesConfig(
+    load_in_4bit=True,
+    bnb_4bit_compute_dtype=torch.bfloat16,
+    bnb_4bit_use_double_quant=True,
+    bnb_4bit_quant_type="nf4"
+)
+
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    quantization_config=quantization_config,
+    device_map="auto"
+)
+```
+
+## Running Benchmarks
+
+```bash
+# Full benchmark suite
+python benchmark.py --model DeepXR/Helion-V2.0-Thinking
+
+# Evaluation suite
+python evaluate.py --model DeepXR/Helion-V2.0-Thinking
+```
+
+## Common Use Cases
+
+### Chatbot
+
+```python
+conversation = []
+
+while True:
+    user_input = input("You: ")
+    if user_input.lower() == 'quit':
+        break
+    
+    conversation.append({"role": "user", "content": user_input})
+    
+    prompt = "\n".join([
+        f"{msg['role'].capitalize()}: {msg['content']}" 
+        for msg in conversation
+    ]) + "\nAssistant:"
+    
+    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+    outputs = model.generate(**inputs, max_new_tokens=512)
+    response = tokenizer.decode(outputs[0], skip_special_tokens=True)
+    response = response.split("Assistant:")[-1].strip()
+    
+    conversation.append({"role": "assistant", "content": response})
+    print(f"Assistant: {response}")
+```
+
+### Document Analysis
+
+```python
+# Read long document
+with open("document.txt", "r") as f:
+    document = f.read()
+
+prompt = f"""{document}
+
+Please provide:
+1. A summary of the main points
+2. Key takeaways
+3. Any recommendations
+
+Summary:"""
+
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+outputs = model.generate(**inputs, max_new_tokens=1024)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+### Code Generation
+
+```python
+prompt = """Write a Python function that:
+1. Takes a list of numbers
+2. Removes duplicates
+3. Returns sorted in descending order
+
+Include type hints and docstring."""
+
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+outputs = model.generate(
+    **inputs,
+    max_new_tokens=512,
+    temperature=0.3  # Lower temperature for code
+)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+## Troubleshooting
+
+### Out of Memory
+
+1. Use quantization (4-bit or 8-bit)
+2. Reduce `max_new_tokens`
+3. Enable gradient checkpointing
+4. Use smaller batch sizes
+
+### Slow Performance
+
+1. Enable Flash Attention 2: `use_flash_attention_2=True`
+2. Use GPU if available
+3. Reduce context length
+4. Use quantization
+
+### Installation Issues
+
+```bash
+# Update pip
+pip install --upgrade pip
+
+# Install from scratch
+pip uninstall transformers torch
+pip install transformers torch accelerate
+
+# CUDA issues
+pip install torch --index-url https://download.pytorch.org/whl/cu121
+```
+
+## Next Steps
+
+- Read the full [README.md](README.md) for detailed documentation
+- Check out [inference.py](inference.py) for more examples
+- Review [safety_wrapper.py](safety_wrapper.py) for safety features
+- Run [benchmark.py](benchmark.py) to test performance
+- See [evaluate.py](evaluate.py) for quality metrics
+
+## Support
+
+For issues and questions:
+- Check the Hugging Face model page
+- Review existing issues
+- Submit a new issue with details
+
+## License
+
+Apache 2.0 - See LICENSE file for details