Manual de IA - Implementação

Modelos e Serviços Disponíveis

⬆ Topo ⬆ Secção ⬇ Próxima

Modelos e Serviços Disponíveis

1. Serviços Comerciais (Cloud)

OpenAI (ChatGPT)

Grátis ChatGPT Free - GPT-4o mini limitado
$20/mês ChatGPT Plus - GPT-4, GPT-4o, custom GPTs
Empresas ChatGPT Team - Para equipas
Empresas ChatGPT Enterprise - Para empresas
Pay-as-you-go API OpenAI - Pagas por uso (tokens)

Anthropic (Claude)

Grátis Claude.ai Free - Claude Sonnet limitado
$20/mês Claude Pro - Claude Opus/Sonnet ilimitado
Pay-as-you-go API Anthropic - Pagas por uso

Google

Grátis Gemini Free - Acesso básico
$20/mês Gemini Advanced - Modelo mais avançado
Grátis Google AI Studio - Com limites
Empresas Vertex AI - Para empresas

Outros Serviços

Microsoft Copilot (integrado no Microsoft 365)
Perplexity AI - Focado em pesquisa
Meta AI - Grátis
Mistral AI - Europeu, versões grátis e pagas

2. Modelos Open Source (Local)

É totalmente possível instalar e executar modelos de IA localmente no teu computador!

Ollama (Recomendado para começar)

Características do Ollama

Interface simples tipo Docker
Roda no teu computador (Windows, Mac, Linux)
Biblioteca enorme de modelos
Completamente grátis
Privacidade total (dados não saem do teu PC)

Principais Modelos Disponíveis no Ollama

Llama 3/3.1/3.2 (Meta) - Excelente qualidade
Mistral - Rápido e eficiente
Phi-3 (Microsoft) - Pequeno mas capaz
Gemma (Google) - Leve
Qwen (Alibaba) - Muito bom para código
DeepSeek - Excelente para programação

Outros Frameworks Locais

LM Studio - Interface gráfica amigável
GPT4All - Muito fácil de usar
Text Generation WebUI - Mais técnico, muito configurável
Jan.ai - Interface bonita, tipo ChatGPT
LocalAI - API compatível com OpenAI

3. Como Funciona o Ollama

Instalação

O processo é muito simples:

# 1. Download de ollama.com
# 2. Instalar um modelo (ex: Llama 3.2)
ollama pull llama3.2

# 3. Correr o modelo
ollama run llama3.2

# 4. Ou usar API local
ollama serve

Vantagens

Vantagem Gratuito e sem limites
Vantagem Privacidade completa
Vantagem Funciona offline
Vantagem Controlo total
Vantagem Sem censura excessiva

Desvantagens

Desvantagem Precisa de hardware razoável (mínimo 8GB RAM, idealmente 16GB+)
Desvantagem Modelos open-source geralmente menos capazes que GPT-4/Claude
Desvantagem Processamento mais lento que cloud
Desvantagem Manutenção por conta própria

4. Requisitos de Hardware

Categoria	Especificações	Modelos Suportados
Mínimo Aceitável	• CPU moderna • 8GB RAM • Sem GPU dedicada	Modelos pequenos (3B-7B parâmetros)
Recomendado	• CPU moderna • 16GB+ RAM • GPU NVIDIA (opcional mas acelera)	Modelos médios (7B-13B)
Ideal	• CPU de topo • 32GB+ RAM • GPU com 8GB+ VRAM	Modelos grandes (70B+)

Montar um Agente de IA para um Website

⬆ Topo ⬆ Secção ⬇ Próxima

Montar um Agente de IA para um Website

Conceito Geral

Um agente de IA num website é essencialmente um chatbot inteligente que interage com visitantes em tempo real. As suas funções principais incluem:

Responder a perguntas sobre produtos/serviços
Auxiliar na navegação do site
Processar pedidos e realizar ações
Fornecer suporte ao cliente automatizado
Qualificar leads e potenciais clientes

Arquitetura Básica

Um chatbot de IA para website é composto por três componentes principais:

Frontend (Interface) - O widget de chat visível no site onde o utilizador escreve mensagens
Backend (Servidor) - Processa pedidos, gere lógica de negócio e comunica com a IA
API de IA - O modelo de linguagem que gera as respostas (GPT, Claude, Ollama, etc.)

Fluxo de Funcionamento

Visitante escreve mensagem no widget
    ↓
Frontend envia via AJAX/Fetch para Backend
    ↓
Backend processa e envia para API de IA
    ↓
API de IA gera resposta
    ↓
Backend recebe e pode processar adicionalmente
    ↓
Resposta retorna ao Frontend
    ↓
Mensagem é exibida ao visitante

Implementação em Laravel

Opção 1: API Cloud (OpenAI/Anthropic)

Esta é a abordagem mais comum para chatbots profissionais com IA de alta qualidade.

Passo 1: Instalação de Dependências

composer require openai-php/laravel

Passo 2: Configuração (.env)

OPENAI_API_KEY=sk-your-key-here
OPENAI_ORGANIZATION=your-org-id

Passo 3: Controller (app/Http/Controllers/ChatbotController.php)

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use OpenAI\Laravel\Facades\OpenAI;

class ChatbotController extends Controller
{
    public function sendMessage(Request $request)
    {
        // Validate input
        $validated = $request->validate([
            'message' => 'required|string|max:1000',
            'conversation_id' => 'nullable|string'
        ]);

        // Build conversation context
        $messages = [
            [
                'role' => 'system',
                'content' => 'You are a helpful assistant for our website. 
                             Answer questions about our products and services 
                             professionally in Portuguese.'
            ],
            [
                'role' => 'user',
                'content' => $validated['message']
            ]
        ];

        // Call OpenAI API
        $result = OpenAI::chat()->create([
            'model' => 'gpt-4',
            'messages' => $messages,
            'max_tokens' => 500,
            'temperature' => 0.7
        ]);

        $reply = $result->choices[0]->message->content;

        // Optional: Store conversation in database
        // ConversationMessage::create([...]);

        return response()->json([
            'success' => true,
            'reply' => $reply,
            'conversation_id' => $validated['conversation_id'] ?? uniqid()
        ]);
    }
}

Passo 4: Route (routes/web.php)

use App\Http\Controllers\ChatbotController;

Route::post('/api/chatbot/message', [ChatbotController::class, 'sendMessage']);

Passo 5: Frontend - Widget HTML (resources/views/layouts/app.blade.php)

<!-- Chat Widget Button -->
<div id="chat-widget">
    <button id="chat-toggle" class="chat-button">
        💬
    </button>
    
    <div id="chat-window" class="chat-window hidden">
        <div class="chat-header">
            <h3>Assistente Virtual</h3>
            <button id="chat-close">✕</button>
        </div>
        
        <div id="chat-messages" class="chat-messages">
            <!-- Messages appear here -->
        </div>
        
        <div class="chat-input">
            <input type="text" id="message-input" 
                   placeholder="Escreva a sua mensagem...">
            <button id="send-button">Enviar</button>
        </div>
    </div>
</div>

<script src="{{ asset('js/chatbot.js') }}"></script>

Passo 6: JavaScript (public/js/chatbot.js)

Este código gere toda a interação do utilizador com o chatbot:

class Chatbot {
    constructor() {
        this.conversationId = null;
        this.initializeElements();
        this.attachEventListeners();
    }

    initializeElements() {
        this.toggleBtn = document.getElementById('chat-toggle');
        this.closeBtn = document.getElementById('chat-close');
        this.chatWindow = document.getElementById('chat-window');
        this.messagesContainer = document.getElementById('chat-messages');
        this.messageInput = document.getElementById('message-input');
        this.sendBtn = document.getElementById('send-button');
    }

    attachEventListeners() {
        this.toggleBtn.addEventListener('click', () => this.toggleChat());
        this.closeBtn.addEventListener('click', () => this.toggleChat());
        this.sendBtn.addEventListener('click', () => this.sendMessage());
        this.messageInput.addEventListener('keypress', (e) => {
            if (e.key === 'Enter') this.sendMessage();
        });
    }

    toggleChat() {
        this.chatWindow.classList.toggle('hidden');
    }

    async sendMessage() {
        const message = this.messageInput.value.trim();
        if (!message) return;

        // Display user message
        this.addMessage(message, 'user');
        this.messageInput.value = '';

        // Show typing indicator
        this.showTypingIndicator();

        try {
            const response = await fetch('/api/chatbot/message', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'X-CSRF-TOKEN': document.querySelector(
                        'meta[name="csrf-token"]'
                    ).content
                },
                body: JSON.stringify({
                    message: message,
                    conversation_id: this.conversationId
                })
            });

            const data = await response.json();
            
            this.hideTypingIndicator();
            
            if (data.success) {
                this.conversationId = data.conversation_id;
                this.addMessage(data.reply, 'bot');
            } else {
                this.addMessage(
                    'Desculpe, ocorreu um erro. Tente novamente.', 
                    'bot'
                );
            }
        } catch (error) {
            this.hideTypingIndicator();
            this.addMessage(
                'Erro de conexão. Verifique sua internet.', 
                'bot'
            );
            console.error('Chatbot error:', error);
        }
    }

    addMessage(text, sender) {
        const messageDiv = document.createElement('div');
        messageDiv.className = `message ${sender}-message`;
        messageDiv.textContent = text;
        this.messagesContainer.appendChild(messageDiv);
        this.messagesContainer.scrollTop = 
            this.messagesContainer.scrollHeight;
    }

    showTypingIndicator() {
        const indicator = document.createElement('div');
        indicator.className = 'typing-indicator';
        indicator.id = 'typing';
        indicator.innerHTML = '<span></span><span></span><span></span>';
        this.messagesContainer.appendChild(indicator);
    }

    hideTypingIndicator() {
        const indicator = document.getElementById('typing');
        if (indicator) indicator.remove();
    }
}

// Initialize chatbot when DOM is ready
document.addEventListener('DOMContentLoaded', () => {
    new Chatbot();
});

Opção 2: Ollama Local (Grátis e Privado)

Vantagens do Ollama

Sem custos de API - completamente grátis
Privacidade total - dados não saem do servidor
Sem limites de requests
Controlo total sobre o modelo
Funciona offline

A implementação é muito semelhante, apenas mudando a chamada da API:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class ChatbotController extends Controller
{
    public function sendMessage(Request $request)
    {
        $validated = $request->validate([
            'message' => 'required|string|max:1000',
        ]);

        // Call Ollama API (running locally on server)
        $response = Http::post('http://localhost:11434/api/generate', [
            'model' => 'llama3.2',
            'prompt' => $this->buildPrompt($validated['message']),
            'stream' => false
        ]);

        if ($response->successful()) {
            $reply = $response->json()['response'];
            
            return response()->json([
                'success' => true,
                'reply' => $reply
            ]);
        }

        return response()->json([
            'success' => false,
            'error' => 'Failed to get response'
        ], 500);
    }

    private function buildPrompt($userMessage)
    {
        return "You are a helpful assistant for a website. 
Answer in Portuguese.

User: {$userMessage}
Assistant:";
    }
}

Implementação em WordPress

Para WordPress, existem duas abordagens principais:

Opção 1: Plugins Prontos (Mais Rápido)

Plugin	Características	Custo
AI Engine	• Integração OpenAI/Anthropic • Chatbot customizável • Suporte para Custom GPTs	Premium (~$60/ano)
Tidio	• Chat com IA integrada • Interface drag-and-drop • Analytics incluído	Freemium
Chatbot with Watson	• IBM Watson AI • Mais robusto • Ideal para empresas	Grátis até limite

Instalação típica de plugin:

WordPress Admin → Plugins → Add New 
→ Pesquisar "AI Engine"
→ Install → Activate 
→ Settings → Configure API Key

Opção 2: Plugin Personalizado (PHP)

Para quem quer controlo total, pode criar um plugin WordPress personalizado:

Estrutura do Pluginwp-content/plugins/custom-ai-chatbot/
├── custom-ai-chatbot.php (ficheiro principal)
├── includes/
│   ├── class-chatbot-api.php
│   └── class-chatbot-widget.php
├── assets/
│   ├── css/chatbot.css
│   └── js/chatbot.js
└── templates/
    └── chatbot-widget.php

Ficheiro Principal (custom-ai-chatbot.php):

<?php
/**
 * Plugin Name: Custom AI Chatbot
 * Description: AI-powered chatbot for WordPress
 * Version: 1.0.0
 * Author: Your Name
 */

if (!defined('ABSPATH')) exit;

class CustomAIChatbot {
    
    public function __construct() {
        add_action('wp_enqueue_scripts', [$this, 'enqueue_scripts']);
        add_action('wp_footer', [$this, 'render_widget']);
        add_action('wp_ajax_chatbot_message', [$this, 'handle_message']);
        add_action('wp_ajax_nopriv_chatbot_message', 
                   [$this, 'handle_message']);
    }
    
    public function enqueue_scripts() {
        wp_enqueue_style(
            'chatbot-css',
            plugin_dir_url(__FILE__) . 'assets/css/chatbot.css'
        );
        
        wp_enqueue_script(
            'chatbot-js',
            plugin_dir_url(__FILE__) . 'assets/js/chatbot.js',
            ['jquery'],
            '1.0.0',
            true
        );
        
        wp_localize_script('chatbot-js', 'chatbotAjax', [
            'ajaxurl' => admin_url('admin-ajax.php'),
            'nonce' => wp_create_nonce('chatbot_nonce')
        ]);
    }
    
    public function render_widget() {
        include plugin_dir_path(__FILE__) . 
              'templates/chatbot-widget.php';
    }
    
    public function handle_message() {
        check_ajax_referer('chatbot_nonce', 'nonce');
        
        $message = sanitize_text_field($_POST['message']);
        
        // Call OpenAI API
        $api_key = get_option('chatbot_openai_key');
        
        $response = wp_remote_post(
            'https://api.openai.com/v1/chat/completions', 
            [
                'headers' => [
                    'Authorization' => 'Bearer ' . $api_key,
                    'Content-Type' => 'application/json'
                ],
                'body' => json_encode([
                    'model' => 'gpt-4',
                    'messages' => [
                        [
                            'role' => 'system',
                            'content' => 'You are a helpful assistant.'
                        ],
                        [
                            'role' => 'user',
                            'content' => $message
                        ]
                    ]
                ]),
                'timeout' => 30
            ]
        );
        
        if (is_wp_error($response)) {
            wp_send_json_error(['message' => 'API Error']);
            return;
        }
        
        $body = json_decode(wp_remote_retrieve_body($response), true);
        $reply = $body['choices'][0]['message']['content'];
        
        wp_send_json_success(['reply' => $reply]);
    }
}

new CustomAIChatbot();

Comparação: Laravel vs WordPress

Aspecto	Laravel	WordPress
Controlo	Total	Limitado por plugins
Customização	Ilimitada	Moderada
Velocidade de Desenvolvimento	Média	Rápida (com plugins)
Performance	Melhor (otimizado)	Depende dos plugins
Manutenção	Requer conhecimento PHP	Mais simples
Custo	Grátis (exceto API)	Grátis ou plugins pagos
Escalabilidade	Excelente	Boa

Funcionalidades Avançadas

1. Memória de Conversação

Permite que o chatbot se lembre do contexto da conversa:

// Laravel - Guardar histórico na sessão
Session::put("chat_history_{$conversationId}", $messages);

// Recuperar para contexto
$history = Session::get("chat_history_{$conversationId}", []);

// Adicionar ao prompt da API
$allMessages = array_merge($history, $newMessage);

2. Integração com Base de Conhecimento (RAG)

O chatbot procura informação relevante no teu site antes de responder:

// Search website content before asking AI
$relevantContent = Post::where('content', 'LIKE', "%{$keyword}%")
                      ->limit(3)
                      ->get();

// Add to AI context
$systemPrompt = "Use this information from our website: " . 
                $relevantContent->pluck('content')->implode("\n\n") .
                "\n\nNow answer the user's question.";

3. Analytics e Monitorização

Rastreia conversas para melhorar o serviço:

// Track conversations in database
ChatLog::create([
    'user_message' => $message,
    'bot_response' => $reply,
    'user_ip' => $request->ip(),
    'user_agent' => $request->userAgent(),
    'timestamp' => now(),
    'satisfied' => null // User feedback
]);

4. Fallback Humano

Transferir para operador humano quando necessário:

// Detect keywords that require human
$humanKeywords = ['falar com humano', 'atendente', 'reclamação'];

if (Str::contains(strtolower($message), $humanKeywords)) {
    return response()->json([
        'success' => true,
        'reply' => 'Vou transferir para um dos nossos operadores...',
        'transfer_to_human' => true
    ]);
}

Treino vs Prompt Engineering

⬆ Topo ⬆ Secção ⬇ Próxima

Treino vs Prompt Engineering

⚠️ Questão Importante: Os packages e plugins já incluem o "treino" do GPT?

Resposta curta: Não existe treino tradicional. O que existe é configuração via prompts.

Esclarecimento de Conceitos

1. Prompt Engineering (O que packages/plugins fazem)

Como Funciona

Defines instruções no momento (system prompt)
Forneces contexto específico (FAQs, produtos, políticas)
Ajustas o comportamento através de prompts
Não modifica o modelo - apenas guia as respostas
Efeito é imediato

Exemplo de System Prompt:

You are a customer support assistant for TechStore Portugal.

GUIDELINES:
- Always respond in Portuguese (Portugal)
- Be professional but friendly
- If you don't know something, admit it
- Never make up product information
- Direct users to contact form for complex issues

COMPANY INFO:
- We sell computers and accessories
- Shipping within 24h for orders before 15h
- 30-day return policy
- Support hours: 9h-18h Mon-Fri

PRODUCTS:
- Laptops: Dell, HP, Lenovo (€400-€2000)
- Desktops: Custom builds available
- Accessories: Mice, keyboards, monitors

Isto NÃO é treino, mas funciona muito bem para a maioria dos casos!

2. Fine-tuning (Treino Real - Raramente Necessário)

O que é Fine-tuning

Treinas o modelo com dados específicos da tua empresa
Requer milhares de exemplos de conversas (mínimo 500-1000)
Muito caro - centenas/milhares de euros
Disponível apenas via API OpenAI (não em ChatGPT Plus)
Processo demora horas/dias
Raramente necessário para chatbots de website

Fine-tuning Explicado em Detalhe

O que é Fine-tuning?

Fine-tuning (afinação) é o processo de re-treinar um modelo de IA pré-existente com dados específicos do teu domínio. É como pegar num estudante universitário genérico e especializá-lo numa área específica através de treino intensivo.

Analogia Prática

Sem Fine-tuning (Prompt Engineering): Contratas um assistente inteligente e dás-lhe um manual de 50 páginas sobre a tua empresa. Ele lê antes de cada tarefa.

Com Fine-tuning: O assistente passa 6 meses a trabalhar na tua empresa, internalizando completamente a cultura, processos e linguagem. Já não precisa de consultar o manual constantemente.

Como Funciona Tecnicamente

Preparação de Dados
- Reúnes milhares de exemplos (conversas, documentos, respostas)
- Formatas em pares pergunta-resposta ou input-output
- Qualidade > Quantidade (mas precisas de ambas)
Processo de Treino
- O modelo aprende padrões específicos dos teus dados
- Ajusta os "pesos" internos da rede neural
- Preserva conhecimento geral mas adiciona especialização
Resultado
- Novo modelo especializado no teu domínio
- Gera respostas mais consistentes e precisas
- Usa automaticamente a tua terminologia e estilo

Exemplo Prático: Suporte Técnico de Software

Cenário: Empresa de software com terminologia técnica muito específica e centenas de tickets de suporte por dia.

// Exemplo de dados para fine-tuning (formato JSONL)

// Ficheiro: training_data.jsonl

{"messages": [
  {"role": "system", "content": "You are TechSupport AI for CloudSync Pro"},
  {"role": "user", "content": "O SyncAgent não está a fazer push para o repo"},
  {"role": "assistant", "content": "Verificou se o SyncAgent tem permissões no CloudSync Dashboard? Aceda a Settings > Agent Permissions e confirme que 'Repository Push' está activado. Se o problema persistir, execute 'syncagent --diagnose' no terminal e envie-me o output."}
]},

{"messages": [
  {"role": "system", "content": "You are TechSupport AI for CloudSync Pro"},
  {"role": "user", "content": "Erro: SYNC_CONFLICT_3402"},
  {"role": "assistant", "content": "O erro SYNC_CONFLICT_3402 indica conflito de versões. Solução: 1) Pare o SyncAgent 2) Execute 'syncagent --resolve-conflicts' 3) Reveja os ficheiros marcados em /conflicts/ 4) Reinicie o agent. Documentação: docs.cloudsync.com/errors/3402"}
]},

// ... mais 1000-10000 exemplos semelhantes ...

Fine-tuning com OpenAI (API)

Passo 1: Preparar Dados

// Script PHP para preparar dados de fine-tuning

<?php

// Collect training data from your support tickets database
$tickets = SupportTicket::with('responses')
    ->where('status', 'resolved')
    ->where('quality_rating', '>=', 4)
    ->limit(2000)
    ->get();

$trainingData = [];

foreach ($tickets as $ticket) {
    $trainingData[] = [
        'messages' => [
            [
                'role' => 'system',
                'content' => 'You are a technical support assistant for our software.'
            ],
            [
                'role' => 'user',
                'content' => $ticket->question
            ],
            [
                'role' => 'assistant',
                'content' => $ticket->best_response
            ]
        ]
    ];
}

// Save as JSONL (JSON Lines format)
$file = fopen('training_data.jsonl', 'w');
foreach ($trainingData as $item) {
    fwrite($file, json_encode($item) . "\n");
}
fclose($file);

echo "Training data prepared: " . count($trainingData) . " examples\n";

Passo 2: Upload e Fine-tuning (OpenAI CLI)

# Upload training file
openai api files.create \
  -f training_data.jsonl \
  -p fine-tune

# Start fine-tuning job
openai api fine_tuning.jobs.create \
  -t file-abc123 \
  -m gpt-3.5-turbo \
  --suffix "techsupport-v1"

# Monitor progress
openai api fine_tuning.jobs.retrieve -i ftjob-xyz789

# After completion, you get a model ID like:
# ft:gpt-3.5-turbo:company-name:techsupport-v1:8Nqpo1x

Passo 3: Usar o Modelo Fine-tuned em Laravel

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use OpenAI\Laravel\Facades\OpenAI;

class FineTunedChatbotController extends Controller
{
    public function sendMessage(Request $request)
    {
        $validated = $request->validate([
            'message' => 'required|string|max:1000'
        ]);

        // Use your fine-tuned model
        $result = OpenAI::chat()->create([
            'model' => 'ft:gpt-3.5-turbo:company-name:techsupport-v1:8Nqpo1x',
            'messages' => [
                [
                    'role' => 'user',
                    'content' => $validated['message']
                ]
            ]
        ]);

        return response()->json([
            'reply' => $result->choices[0]->message->content
        ]);
    }
}

Custos de Fine-tuning (OpenAI)

Aspecto	Custo Aproximado
Treino (GPT-3.5-turbo)	$0.008 por 1K tokens
Treino (GPT-4)	$0.03 por 1K tokens
Uso do modelo fine-tuned	~2x o preço do modelo base
Exemplo: 1M tokens de treino	$8 (GPT-3.5) ou $30 (GPT-4)
Total para projecto médio	$100-$500 inicial + custos de uso

Fine-tuning com Ollama (Modelos Locais)

Com Ollama, tens controlo total e podes fazer fine-tuning gratuitamente, mas é mais técnico.

Possibilidades com Ollama

✅ O que podes fazer

Fine-tuning completo de modelos open-source (Llama, Mistral, etc.)
Custo zero - apenas hardware (GPU recomendada)
Privacidade total - dados nunca saem do teu servidor
Controlo completo - podes experimentar livremente
Integração directa com Laravel

❌ Desafios

Requer conhecimento técnico - Machine Learning, Python, GPU
Hardware exigente - GPU com 16GB+ VRAM recomendada
Tempo de treino - Pode levar dias
Complexidade - Mais difícil que usar API OpenAI

Processo de Fine-tuning com Ollama

Opção 1: Usar Modelfiles (Simples, mas limitado)

Ollama permite criar modelos customizados através de Modelfiles. Não é verdadeiro fine-tuning, mas permite adicionar conhecimento específico:

# Criar Modelfile
# File: Modelfile

FROM llama3.2

# System prompt permanente
SYSTEM """
You are a technical support assistant for CloudSync Pro software.

PRODUCT KNOWLEDGE:
- CloudSync Pro is a file synchronization tool
- Common errors: SYNC_CONFLICT_3402, AUTH_FAILED_1001
- SyncAgent is the background service
- Dashboard URL: app.cloudsync.com

GUIDELINES:
- Always respond in Portuguese
- Provide specific error codes when relevant
- Link to documentation when appropriate
"""

# Parâmetros de temperatura, etc.
PARAMETER temperature 0.7
PARAMETER top_p 0.9

# Criar o modelo custom no Ollama
ollama create cloudsync-support -f Modelfile

# Testar
ollama run cloudsync-support "O SyncAgent não inicia"

Usar em Laravel:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class OllamaCustomChatbotController extends Controller
{
    public function sendMessage(Request $request)
    {
        $validated = $request->validate([
            'message' => 'required|string|max:1000'
        ]);

        // Call Ollama with custom model
        $response = Http::post('http://localhost:11434/api/generate', [
            'model' => 'cloudsync-support',  // Your custom model
            'prompt' => $validated['message'],
            'stream' => false
        ]);

        if ($response->successful()) {
            return response()->json([
                'success' => true,
                'reply' => $response->json()['response']
            ]);
        }

        return response()->json([
            'success' => false,
            'error' => 'Failed to get response'
        ], 500);
    }
}

Opção 2: Fine-tuning Real com Unsloth/LoRA (Avançado)

Para verdadeiro fine-tuning de modelos Llama/Mistral, usa ferramentas como Unsloth ou LoRA:

                    Ferramentas para Fine-tuning Local
                    Unsloth - Framework rápido para fine-tuning (2x-5x mais rápido)
LoRA/QLoRA - Técnica eficiente que usa menos memória
Axolotl - Framework completo para treino
LLaMA-Factory - Interface gráfica para fine-tuning

                

# Exemplo usando Unsloth (Python)

# install_unsloth.sh
pip install unsloth
pip install torch transformers datasets

# fine_tune_llama.py
from unsloth import FastLanguageModel
import torch

# Load base model
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/llama-3-8b-bnb-4bit",
    max_seq_length = 2048,
    dtype = None,
    load_in_4bit = True,
)

# Prepare for fine-tuning with LoRA
model = FastLanguageModel.get_peft_model(
    model,
    r = 16,  # LoRA rank
    target_modules = ["q_proj", "k_proj", "v_proj", "o_proj"],
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
)

# Load your training data
from datasets import load_dataset
dataset = load_dataset("json", data_files="training_data.jsonl")

# Training
from transformers import TrainingArguments, Trainer

trainer = Trainer(
    model = model,
    train_dataset = dataset["train"],
    args = TrainingArguments(
        per_device_train_batch_size = 2,
        gradient_accumulation_steps = 4,
        warmup_steps = 5,
        max_steps = 60,
        learning_rate = 2e-4,
        output_dir = "outputs",
    ),
)

trainer.train()

# Save the fine-tuned model
model.save_pretrained("llama3-cloudsync-finetuned")

Passo 3: Converter para Ollama

# Create Modelfile for your fine-tuned model
# Modelfile

FROM ./llama3-cloudsync-finetuned

# Import into Ollama
ollama create cloudsync-finetuned -f Modelfile

# Test
ollama run cloudsync-finetuned "Como resolver erro SYNC_CONFLICT_3402?"

Passo 4: Integração Laravel (Igual ao anterior)

<?php

// O código Laravel é idêntico, apenas muda o nome do modelo:

$response = Http::post('http://localhost:11434/api/generate', [
    'model' => 'cloudsync-finetuned',  // Your fine-tuned model
    'prompt' => $validated['message'],
    'stream' => false
]);

Comparação: Fine-tuning OpenAI vs Ollama

Aspecto	OpenAI Fine-tuning	Ollama Fine-tuning
Facilidade	⭐⭐⭐⭐⭐ Muito fácil	⭐⭐ Requer expertise
Custo Inicial	$100-$500	$0 (só hardware)
Custo de Uso	~$0.002/1K tokens	$0 (grátis)
Qualidade	⭐⭐⭐⭐⭐ Excelente	⭐⭐⭐⭐ Muito boa
Privacidade	⭐⭐ Dados na cloud	⭐⭐⭐⭐⭐ 100% local
Tempo Setup	Horas	Dias/Semanas
Hardware Necessário	Nenhum	GPU 16GB+ VRAM
Manutenção	Zero	Alta
Flexibilidade	⭐⭐⭐ Limitada	⭐⭐⭐⭐⭐ Total

Quando Vale a Pena Fine-tuning?

✅ Vale a Pena se:

Tens 10.000+ exemplos de conversas de alta qualidade
Linguagem/terminologia é muito específica e única
Prompt engineering + RAG não conseguem resultados aceitáveis
Precisas de consistência absoluta nas respostas
Volume de uso é muito alto (custo justifica investimento)
Tens orçamento (€1000-5000) ou hardware adequado
É um projecto de longo prazo (2+ anos)

❌ Não Vale a Pena se:

Tens menos de 1000 exemplos
O domínio é genérico (suporte geral, FAQs básicas)
Prompt engineering já dá resultados 80%+ bons
É um projecto piloto ou de curto prazo
Não tens orçamento ou hardware
Não tens expertise técnica (para Ollama)

Recomendação Prática: Abordagem Progressiva

                    🎯 Estratégia Recomendada
                    Fase 1: Prompt Engineering (Semana 1)
                            Cria chatbot com prompts bem escritos
Testa com utilizadores reais
Custo: €0-50 (apenas API)

                        
Fase 2: RAG (Semanas 2-4)
                            Adiciona base de conhecimento
Implementa busca semântica
Mede melhoria de qualidade

                        
Fase 3: Decisão sobre Fine-tuning (Mês 2+)
                            Se Prompt+RAG atinge 85%+ satisfação → Não faças fine-tuning
Se precisas de mais → Avalia custo/benefício do fine-tuning

                        

                

Quando considerar Fine-tuning:

Tens 10.000+ conversas reais anotadas
O modelo precisa de linguagem muito específica (jargão técnico único)
Prompt engineering não consegue o resultado pretendido
Tens orçamento para investir (€1000+)
É um projeto de longo prazo

3. RAG - Retrieval Augmented Generation (Solução Prática)

                    Como funciona o RAG
                    Utilizador faz pergunta: "Qual o prazo de entrega?"
Sistema procura na base de conhecimento (FAQs, produtos, políticas)
Encontra informação relevante sobre prazos de entrega
Injeta essa informação no prompt enviado à IA
IA responde com base na informação fornecida

                

Onde o RAG Procura? Base de Conhecimento

O RAG pode procurar em múltiplas fontes. A base de conhecimento pode ser:

Fontes Comuns para RAG

Base de dados relacional - MySQL, PostgreSQL, SQL Server
- Tabelas: FAQs, produtos, artigos, documentação
- Pesquisa: SQL LIKE, FULLTEXT SEARCH, ou busca semântica
Base de dados NoSQL - MongoDB, Elasticsearch
- Documentos JSON com conteúdo
- Pesquisa: Text search, agregações
Vector Database - Pinecone, Weaviate, ChromaDB, Qdrant
- Armazena embeddings (representações vectoriais do texto)
- Pesquisa semântica (por significado, não palavras exactas)
Ficheiros - PDFs, DOCX, TXT
- Documentação técnica, manuais, contratos
- Processados e indexados antes da pesquisa
APIs externas - CRM, ERP, sistemas internos
- Dados em tempo real de outros sistemas
CMS/Website - WordPress, Laravel posts/pages
- Conteúdo publicado no site

Tipos de Pesquisa RAG

1. Pesquisa por Palavras-chave (Keyword Search)

Como funciona: Procura palavras exactas ou similares no texto

Tecnologia: SQL LIKE, FULLTEXT, Elasticsearch

Vantagens: Simples, rápida, não requer treino

Desvantagens: Não entende contexto/sinónimos

// Laravel - Keyword Search em MySQL
$query = "prazo de entrega";

$results = DB::table('faqs')
    ->where('question', 'LIKE', "%{$query}%")
    ->orWhere('answer', 'LIKE', "%{$query}%")
    ->limit(3)
    ->get();

2. Pesquisa Semântica (Semantic Search)

Como funciona: Procura por significado, não palavras exactas

Tecnologia: Embeddings + Vector Database

Vantagens: Entende sinónimos, contexto, intenção

Desvantagens: Mais complexo, requer embeddings

Exemplo de diferença:

Pergunta: "Quanto tempo demora o envio?"
Keyword: Procura "tempo demora envio" → Pode não encontrar
Semantic: Entende que "envio" = "entrega" → Encontra "prazo de entrega"

Implementação RAG Básico (Keyword Search)

Exemplo 1: MySQL com Laravel

// 1. Estrutura da tabela (migration)
Schema::create('knowledge_base', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->string('category'); // 'faq', 'product', 'policy'
    $table->timestamps();
    
    // Índice para pesquisa rápida
    $table->fullText(['title', 'content']);
});

// 2. Controller com RAG
public function sendMessage(Request $request)
{
    $userMessage = $request->input('message');
    
    // Extract keywords (simplificado)
    $keywords = explode(' ', strtolower($userMessage));
    
    // Search knowledge base
    $relevantDocs = DB::table('knowledge_base')
        ->where(function($query) use ($keywords) {
            foreach ($keywords as $keyword) {
                $query->orWhere('title', 'LIKE', "%{$keyword}%")
                      ->orWhere('content', 'LIKE', "%{$keyword}%");
            }
        })
        ->limit(3)
        ->get();
    
    // Build context from results
    $context = "KNOWLEDGE BASE:\n\n";
    foreach ($relevantDocs as $doc) {
        $context .= "Title: {$doc->title}\n";
        $context .= "Content: {$doc->content}\n\n";
    }
    
    // Send to AI with context
    $messages = [
        [
            'role' => 'system',
            'content' => 'You are a helpful assistant. Use ONLY the following information to answer. If the information is not in the knowledge base, say you don\'t know.'
        ],
        [
            'role' => 'system',
            'content' => $context
        ],
        [
            'role' => 'user',
            'content' => $userMessage
        ]
    ];
    
    $result = OpenAI::chat()->create([
        'model' => 'gpt-4',
        'messages' => $messages
    ]);
    
    return response()->json([
        'reply' => $result->choices[0]->message->content
    ]);
}

Exemplo 2: Pesquisa em Ficheiros (PDFs, DOCX)

// 1. Processar e indexar ficheiros ao carregar
public function uploadDocument(Request $request)
{
    $file = $request->file('document');
    
    // Extract text from PDF/DOCX
    if ($file->extension() === 'pdf') {
        $text = $this->extractPdfText($file);
    } elseif ($file->extension() === 'docx') {
        $text = $this->extractDocxText($file);
    }
    
    // Save to database for searching
    KnowledgeDocument::create([
        'filename' => $file->getClientOriginalName(),
        'content' => $text,
        'file_path' => $file->store('documents')
    ]);
}

private function extractPdfText($file)
{
    // Using smalot/pdfparser package
    $parser = new \Smalot\PdfParser\Parser();
    $pdf = $parser->parseFile($file->path());
    return $pdf->getText();
}

// 2. Usar na pesquisa RAG (igual ao exemplo anterior)
$relevantDocs = KnowledgeDocument::where('content', 'LIKE', "%{$keyword}%")
    ->limit(3)
    ->get();

Implementação RAG Avançado (Semantic Search)

Para pesquisa semântica, precisas de embeddings (representações vectoriais do texto):

// 1. Gerar embeddings para documentos
public function generateEmbeddings()
{
    $documents = KnowledgeDocument::all();
    
    foreach ($documents as $doc) {
        // Call OpenAI Embeddings API
        $response = OpenAI::embeddings()->create([
            'model' => 'text-embedding-ada-002',
            'input' => $doc->content
        ]);
        
        $embedding = $response->embeddings[0]->embedding;
        
        // Save embedding (array of floats)
        $doc->update([
            'embedding' => json_encode($embedding)
        ]);
    }
}

// 2. Pesquisa semântica
public function semanticSearch($query)
{
    // Get query embedding
    $response = OpenAI::embeddings()->create([
        'model' => 'text-embedding-ada-002',
        'input' => $query
    ]);
    
    $queryEmbedding = $response->embeddings[0]->embedding;
    
    // Calculate similarity with all documents
    $documents = KnowledgeDocument::all();
    $results = [];
    
    foreach ($documents as $doc) {
        $docEmbedding = json_decode($doc->embedding);
        
        // Cosine similarity
        $similarity = $this->cosineSimilarity($queryEmbedding, $docEmbedding);
        
        $results[] = [
            'document' => $doc,
            'score' => $similarity
        ];
    }
    
    // Sort by similarity and return top 3
    usort($results, fn($a, $b) => $b['score'] <=> $a['score']);
    
    return array_slice($results, 0, 3);
}

private function cosineSimilarity($vec1, $vec2)
{
    $dotProduct = 0;
    $magnitude1 = 0;
    $magnitude2 = 0;
    
    for ($i = 0; $i < count($vec1); $i++) {
        $dotProduct += $vec1[$i] * $vec2[$i];
        $magnitude1 += $vec1[$i] * $vec1[$i];
        $magnitude2 += $vec2[$i] * $vec2[$i];
    }
    
    return $dotProduct / (sqrt($magnitude1) * sqrt($magnitude2));
}

RAG com Vector Database (Recomendado para Produção)

Para aplicações sérias, usa uma vector database especializada:

// Exemplo com Pinecone (vector database)

// 1. Setup (uma vez)
composer require probots-io/pinecone-php

// 2. Indexar documentos
use Probots\Pinecone\Client as Pinecone;

$pinecone = new Pinecone(env('PINECONE_API_KEY'));
$index = $pinecone->index('knowledge-base');

// Add document
$embedding = OpenAI::embeddings()->create([
    'model' => 'text-embedding-ada-002',
    'input' => $document->content
])->embeddings[0]->embedding;

$index->vectors()->upsert([
    'vectors' => [
        [
            'id' => "doc_{$document->id}",
            'values' => $embedding,
            'metadata' => [
                'title' => $document->title,
                'content' => $document->content
            ]
        ]
    ]
]);

// 3. Pesquisar (muito rápido, mesmo com milhões de documentos)
public function ragSearch($query)
{
    // Get query embedding
    $queryEmbedding = OpenAI::embeddings()->create([
        'model' => 'text-embedding-ada-002',
        'input' => $query
    ])->embeddings[0]->embedding;
    
    // Search in Pinecone
    $results = $index->vectors()->query([
        'vector' => $queryEmbedding,
        'topK' => 3,
        'includeMetadata' => true
    ]);
    
    // Build context
    $context = "";
    foreach ($results['matches'] as $match) {
        $context .= $match['metadata']['content'] . "\n\n";
    }
    
    return $context;
}

Comparação de Abordagens RAG

Abordagem	Precisão	Complexidade	Custo	Caso de Uso
SQL LIKE	⭐⭐	Muito Baixa	€0	Protótipos, FAQs simples
MySQL FULLTEXT	⭐⭐⭐	Baixa	€0	Sites pequenos/médios
Elasticsearch	⭐⭐⭐⭐	Média	€20-100/mês	Sites grandes, e-commerce
Embeddings DIY	⭐⭐⭐⭐	Alta	€10-50/mês	Projetos custom
Vector DB	⭐⭐⭐⭐⭐	Média	€50-200/mês	Produção, escala

Recomendação por Fase do Projeto

🎯 Estratégia Recomendada

MVP/Protótipo: SQL LIKE - Rápido de implementar, testa o conceito
Lançamento Inicial: MySQL FULLTEXT ou Elasticsearch - Qualidade aceitável, baixo custo
Escala/Produção: Vector Database (Pinecone, Weaviate) - Melhor qualidade, escalável

Nota: Podes começar simples e migrar gradualmente. O importante é ter ALGUM sistema de RAG funcionando desde o início.

Comparação das Abordagens

Abordagem	Custo	Complexidade	Eficácia	Tempo Setup
Prompt Engineering	€0	Baixa	⭐⭐⭐⭐	Minutos
RAG (Prompt + Search)	€0-€50	Média	⭐⭐⭐⭐⭐	Horas/Dias
Fine-tuning	€1000+	Alta	⭐⭐⭐⭐⭐	Semanas

O que Packages/Plugins Incluem

✅ Incluem Sempre

Sistema de prompts - Configuração de system prompts
Interface de configuração - Definir comportamento do bot
Gestão de conversações - Histórico e contexto

✅ Alguns Incluem (Versões Premium)

RAG básico - Pesquisa em FAQs/documentos
Analytics - Relatórios de conversas
A/B Testing - Testar diferentes prompts

❌ Não Incluem

Fine-tuning - Treino real do modelo
Modelos proprietários - Precisas de API externa
Infraestrutura GPU - Para modelos locais

Recomendação Prática

Para 95% dos Casos: Prompt Engineering + RAG

Porquê?

✅ Rápido de implementar - Funcional em horas/dias
✅ Custo baixo - Apenas API calls (€20-100/mês)
✅ Muito eficaz - Resolve 90%+ das necessidades
✅ Fácil de ajustar - Mudas prompts em tempo real
✅ Sem dependências complexas - Não precisa treino

Quando Considerar Fine-tuning:

❌ Prompt engineering + RAG não funcionam
✅ Tens budget significativo (€5000+)
✅ Tens milhares de exemplos de conversas reais
✅ É um projeto de longo prazo (1+ anos)
✅ Precisas de linguagem muito específica

Relação com Objetivo 4 (Prompt Engineering)

Sim, está diretamente relacionado! O objetivo 4 do curso - "Dominar prompt engineering para criar conteúdo em escala" - é exactamente a habilidade que precisas para configurar chatbots eficazes.

Prompt Engineering é a Skill Fundamental

Configurar chatbots - 90% do trabalho é escrever bons prompts
Definir personalidade - Tom, estilo, comportamento
Gerir contexto - O que o bot sabe e como usa essa informação
Optimizar respostas - Melhorar qualidade iterativamente
Criar conteúdo - Blogs, emails, descrições de produtos

Dominar prompt engineering permite-te criar chatbots sofisticados sem precisar de treinar modelos, poupando tempo e dinheiro enquanto obténs resultados excelentes.

Comparação de Plataformas

⬆ Topo ⬆ Secção ⬇ Próxima

Comparação de Plataformas

Característica	ChatGPT Plus	Claude Pro	Ollama (Local)
Custo	$20/mês	$20/mês	Grátis
Qualidade	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Privacidade	⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
Velocidade	Rápido	Rápido	Depende do PC
Offline	❌	❌	✅
Custom GPTs	✅	❌	✅ (com configuração)
Integração API	✅ (extra)	✅ (extra)	✅ (incluído)