docs/CUSTOM_FIELDS.md

Campos Customizados no Dataset (v1.2+)

Visão Geral

A partir da versão 1.2, o OktoScript permite definir campos customizados para input e output no bloco DATASET. Além disso, você pode especificar campos de contexto que serão automaticamente incluídos no prompt durante o treinamento. Isso oferece flexibilidade total para trabalhar com datasets complexos que incluem informações contextuais (como menu, drinks, promoções, etc.).

Sintaxe

DATASET {
    train: "dataset/train.jsonl"
    validation: "dataset/val.jsonl"
    format: "jsonl"
    
    # Campos customizados (opcional)
    input_field: "input"      # Nome da coluna de entrada
    output_field: "target"    # Nome da coluna de saída (ou use target_field)
    
    # Campos de contexto (opcional) - incluídos automaticamente no prompt
    context_fields: ["menu", "drinks", "promotions"]
}

Resolução Automática de Campos

Se você não especificar input_field e output_field, o OktoEngine tentará encontrar os campos automaticamente na seguinte ordem:

Para modelos Seq2Seq (T5, BART, etc.):

1. input + output (padrão mais comum)
2. input + target (alternativa comum)
3. text (campo único, usado para ambos)
4. Primeiro campo string encontrado (fallback)

Para modelos Causal (GPT, etc.):

1. input + output (concatenados)
2. input + target (concatenados)
3. text (campo único)
4. Primeiro campo string encontrado (fallback)

Exemplos de Uso

Exemplo 1: Dataset com input e target

DATASET {
    train: "dataset/train.jsonl"
    format: "jsonl"
    input_field: "input"
    output_field: "target"
}

Dataset JSONL:

{"input": "User: Olá", "target": "Assistant: Olá! Como posso ajudar?"}
{"input": "User: Tudo bem?", "target": "Assistant: Sim, tudo ótimo!"}

Exemplo 2: Dataset com campos diferentes

DATASET {
    train: "dataset/conversations.jsonl"
    format: "jsonl"
    input_field: "question"
    output_field: "answer"
}

Dataset JSONL:

{"question": "Qual é a capital do Brasil?", "answer": "Brasília"}
{"question": "Quem descobriu o Brasil?", "answer": "Pedro Álvares Cabral"}

Exemplo 3: Dataset com nomes em português

DATASET {
    train: "dataset/treino.jsonl"
    format: "jsonl"
    input_field: "entrada"
    output_field: "saida"
}

Dataset JSONL:

{"entrada": "Traduza: Hello", "saida": "Olá"}
{"entrada": "Traduza: Goodbye", "saida": "Adeus"}

Exemplo 4: Sem especificar campos (auto-detecção)

DATASET {
    train: "dataset/train.jsonl"
    format: "jsonl"
    # input_field e output_field não especificados
    # O engine tentará encontrar automaticamente
}

O engine tentará:

• input + output → se não encontrar
• input + target → se não encontrar
• text → se não encontrar
• Primeiro campo string → fallback

Compatibilidade

Retrocompatibilidade

Scripts antigos continuam funcionando sem modificação:

# Script v1.0/v1.1 - funciona perfeitamente
DATASET {
    train: "dataset/train.jsonl"
    validation: "dataset/val.jsonl"
}

O engine detectará automaticamente input/output ou input/target.

Aliases Suportados

• output_field e target_field são equivalentes
• Ambos podem ser usados para definir o campo de saída

DATASET {
    train: "dataset/train.jsonl"
    input_field: "input"
    output_field: "target"   # ou target_field: "target"
}

Casos de Uso

1. Datasets de Terceiros

Quando você usa datasets de repositórios públicos que podem ter nomes de colunas diferentes:

DATASET {
    train: "datasets/alpaca_pt.jsonl"
    input_field: "instruction"
    output_field: "response"
}

2. Migração de Formatos

Ao migrar de outros frameworks que usam convenções diferentes:

DATASET {
    train: "dataset/old_format.jsonl"
    input_field: "prompt"
    output_field: "completion"
}

3. Datasets Multilíngues

Para datasets que misturam idiomas nos nomes das colunas:

DATASET {
    train: "dataset/mixed.jsonl"
    input_field: "entrada"
    output_field: "saida"
}

Validação

O OktoEngine valida que:

• Os campos especificados existem no dataset
• Os campos contêm dados válidos (strings)
• O formato do dataset é compatível

Dicas

1. Use campos customizados quando necessário: Se seu dataset já usa input/output ou input/target, não precisa especificar.

2. Teste primeiro: Use okto validate para verificar se os campos estão corretos antes de treinar.

3. Consistência: Mantenha os mesmos nomes de campos em train, validation e test.

4. Documentação: Documente os nomes de campos customizados no seu projeto para facilitar colaboração.

Troubleshooting

Erro: "Field 'X' not found in dataset"

Causa: O campo especificado não existe no dataset.

Solução:

• Verifique os nomes das colunas no seu dataset
• Use okto validate para ver quais campos foram detectados
• Remova input_field/output_field para usar auto-detecção

Erro: "No input/output fields found"

Causa: O engine não conseguiu encontrar campos válidos.

Solução:

• Especifique explicitamente input_field e output_field
• Verifique se o dataset tem pelo menos um campo string

Dataset funciona sem especificar campos, mas falha com campos customizados

Causa: Nome do campo incorreto ou com espaços/caracteres especiais.

Solução:

• Use exatamente o nome da coluna como aparece no JSON
• Evite espaços ou caracteres especiais nos nomes das colunas

Exemplo Completo

# okto_version: "1.2"
PROJECT "custom_fields_example"

DATASET {
    train: "dataset/train.jsonl"
    validation: "dataset/val.jsonl"
    format: "jsonl"
    type: "chat"
    
    # Campos customizados
    input_field: "user_message"
    output_field: "assistant_response"
}

MODEL {
    base: "t5-small"
    device: "auto"
}

TRAIN {
    epochs: 3
    batch_size: 8
    learning_rate: 0.0001
}

EXPORT {
    format: ["okm"]
    path: "export/"
}

---

Versão: 1.2+
Última atualização: 2024