# AI FAQ Generation Guide

**Last Updated:** 2026-01-13

Complete guide for using AI-powered FAQ answer generation.

## Overview

The AI FAQ generation system uses OpenAI API to automatically generate high-quality FAQ answers that follow best practices: 40-80 words, du tone, natural keyword integration.

## Prerequisites

### 1. OpenAI API Key Setup

See `OPENAI_API_KEY_SETUP.md` for complete setup instructions.

**Quick setup:**

```bash
# Option 1: Environment variable
export OPENAI_API_KEY=sk-your-key-here

# Option 2: Config file
# Create v2/config/openai-api-key.php with your key
```

### 2. FAQ Questions Required

Generate FAQ questions first:

```bash
php v2/scripts/blog/generate-faq-questions.php --post=slug --category=category
```

## Usage

### Generate FAQ Answers (AI)

```bash
php v2/scripts/blog/generate-faq-answers-ai.php --post=slug --category=category
```

**What it does:**

- Loads FAQ questions from research data
- Generates answers using OpenAI API
- Follows best practices (40-80 words, du tone)
- Integrates keywords naturally
- Saves to `faq-answers-ai.json`

**Options:**

- `--dry-run` - Test without API calls

### Complete Workflow

```bash
php v2/scripts/blog/generate-faqs-complete.php --post=slug --category=category
```

**This single command:**

1. Generates FAQ questions
2. Generates FAQ answers (AI-powered)
3. Adds keywords automatically
4. Adds links automatically
5. Validates quality

## How It Works

### 1. Question Analysis

The system loads FAQ questions from:

- `docs/content/blog/posts/{category}/{slug}/data/faq-questions.json`

### 2. Context Extraction

Extracts post content context:

- First 500 words of post content
- Primary keyword
- Post title and category

### 3. AI Generation

Uses OpenAI GPT-3.5-turbo with custom prompt:

- German language
- Du tone (informal)
- 40-80 word target
- Keyword integration
- Structured format (answer → context → actionable)

### 4. Quality Validation

Validates generated answers:

- Word count (40-80 words)
- Keyword presence
- Readability
- Structure

## Prompt Template

The system uses this prompt template:

```
Du bist ein SEO-Experte für deutsche Arbeitsrechtsthemen.
Erstelle eine FAQ-Antwort für die folgende Frage.

Frage: {QUESTION}
Kontext (Blog-Post-Inhalt): {CONTEXT}
Primäres Keyword: {KEYWORD}

Anforderungen:
- Länge: 40-80 Wörter
- Struktur: Direkte Antwort (10-15 Wörter) → Kontext (20-40 Wörter) → Handlungsempfehlung (10-15 Wörter)
- Ton: Duzen (informal "du")
- Keyword: Natürlich integrieren, nicht forciert
- Sprache: Deutsch
- Stil: Professionell aber zugänglich

Antworte NUR mit der FAQ-Antwort, ohne zusätzliche Erklärungen.
```

## Cost Tracking

The system automatically tracks API costs:

- **Model:** GPT-3.5-turbo (default)
- **Pricing:** ~$0.0015 per 1K input tokens, $0.002 per 1K output tokens
- **Average cost per FAQ:** ~$0.001-0.002

**View costs after generation:**

```php
$costSummary = get_openai_cost_summary();
print_r($costSummary);
```

## Best Practices

### 1. Review Generated Answers

Always review AI-generated answers:

- Check accuracy
- Verify keyword integration
- Ensure natural tone
- Validate word count

### 2. Manual Refinement

AI answers are starting points:

- Refine for accuracy
- Add specific details
- Include internal links
- Enhance with examples

### 3. Batch Processing

For multiple posts:

```bash
# Process all posts
php v2/scripts/blog/generate-faq-answers-ai.php --all

# Or process by category
for post in $(ls v2/data/blog/posts/lexikon/*.json); do
    slug=$(basename $post .json)
    php v2/scripts/blog/generate-faq-answers-ai.php --post=$slug --category=lexikon
done
```

### 4. Rate Limiting

The script includes rate limiting:

- 1 second delay between requests
- Prevents API rate limit errors
- Adjustable in script if needed

## Troubleshooting

### Error: "OpenAI API key not configured"

**Solution:** Set API key (see `OPENAI_API_KEY_SETUP.md`)

### Error: "FAQ questions file not found"

**Solution:** Generate questions first:

```bash
php v2/scripts/blog/generate-faq-questions.php --post=slug --category=category
```

### Error: "Rate limit exceeded"

**Solution:**

- Wait before retrying
- Check OpenAI dashboard for limits
- Consider upgrading plan

### Poor Quality Answers

**Solution:**

- Review prompt template
- Provide better context
- Refine manually after generation
- Consider using GPT-4 for complex topics

## Example Workflow

```bash
# 1. Generate FAQ questions
php v2/scripts/blog/generate-faq-questions.php --post=minijob --category=lexikon

# 2. Generate FAQ answers (AI)
php v2/scripts/blog/generate-faq-answers-ai.php --post=minijob --category=lexikon

# 3. Review generated answers
# Check: docs/content/blog/posts/lexikon/minijob/data/faq-answers-ai.json

# 4. Integrate into post
# Manually add to post JSON or use enhancement script

# 5. Validate quality
php v2/scripts/blog/validate-expansion-quality.php --post=minijob --category=lexikon
```

## Related Documentation

- `OPENAI_API_KEY_SETUP.md` - API key setup guide
- `FAQ_AUTOMATION_IMPLEMENTATION_SUMMARY.md` - Complete feature overview
- `CONTENT_CREATION_WORKFLOW.md` - Workflow integration
- `FAQ_BEST_PRACTICES.md` - Content guidelines