Spaces:

Erinaldorodrigues
/

Vscode

Running

App Files Files Community

Vscode / TUTORIAL.md

Erinaldorodrigues

Add transparent prediction radar

7293dcc 4 days ago

preview code

Raw

History Blame Contribute Delete

9.62 kB

Tutorial passo a passo — Safe Bet AI Precision v2

1. O que esta versão precisa

O projeto roda em Docker e não usa GPU nem API de IA.

Obrigatório:

um Space Docker que possa executar compute;
token gratuito do football-data.org;
API key gratuita do The Odds API;
uma conta no cron-job.org;
três Secrets no Hugging Face.

Recomendado:

Dataset privado no Hugging Face para guardar histórico/cache.

2. Criar as chaves

football-data.org

Crie uma conta e copie seu token.

Secret:

FOOTBALL_DATA_TOKEN

The Odds API

Crie uma conta e copie sua API key.

Secret:

ODDS_API_KEY

Segredo do cron

Crie uma senha grande e aleatória, por exemplo com um gerenciador de senhas.

Secret:

CRON_SECRET

Não use uma senha curta e não coloque o valor na URL.

3. Enviar o projeto para o Space

O Space deve usar SDK Docker.

O README.md já possui:

sdk: docker
app_port: 7860

Extraia o ZIP e envie todo o conteúdo da pasta para a raiz do repositório do Space.

A raiz precisa ficar assim:

Dockerfile
README.md
requirements.txt
app/
tests/
...

Não coloque uma pasta extra como:

safe-bet-ai-v2-precision/safe-bet-ai-v2-precision/app

O Dockerfile deve estar na raiz.

4. Secrets no Hugging Face

No Space:

Settings
→ Variables and secrets
→ New secret

Crie exatamente:

FOOTBALL_DATA_TOKEN
ODDS_API_KEY
CRON_SECRET

Valores são as chaves criadas anteriormente.

5. Variables recomendadas

Em Variables:

ODDS_REGIONS=eu
HISTORY_DAYS=240
SCAN_HORIZON_HOURS=36
MIN_SCAN_INTERVAL_MINUTES=180

MIN_SAFE_SCORE=76
MIN_PROBABILITY=0.64
MIN_CONSERVATIVE_PROBABILITY=0.57
MIN_BOOKMAKERS=3
MIN_NAME_SCORE=82

TOP_PICKS_LIMIT=10
TZ_DISPLAY=America/Sao_Paulo

Ligas:

ODDS_SPORT_KEYS=soccer_epl,soccer_efl_champ,soccer_germany_bundesliga,soccer_italy_serie_a,soccer_spain_la_liga,soccer_france_ligue_one,soccer_brazil_campeonato,soccer_netherlands_eredivisie,soccer_portugal_primeira_liga,soccer_uefa_champs_league

Não acrescente ligas arbitrárias. A versão Precision só aceita ligas com mapeamento explícito para o football-data.org.

6. Build

Depois do upload, acompanhe:

Space → Logs

O final esperado contém Uvicorn na porta 7860.

Teste:

https://SEU-USUARIO-SEU-SPACE.hf.space/api/health

Você deve receber JSON com:

{
  "ok": true,
  "ready": true,
  "version": "2.2-precision"
}

Confira também:

configured.football_data = true
configured.odds_api = true
configured.cron_secret = true

Se algum estiver false, o nome do Secret está errado ou não foi salvo.

7. Primeiro scan manual

Use:

curl -X POST \
  'https://SEU-USUARIO-SEU-SPACE.hf.space/api/admin/scan?wait=1' \
  -H 'X-Cron-Secret: SEU_CRON_SECRET'

Atenção no primeiro scan

A versão v2 pode buscar a temporada atual e a anterior quando a amostra atual é pequena.

O football-data.org tem limite gratuito por minuto e o bot respeita esse limite. Por isso o primeiro bootstrap pode levar cerca de 1–2 minutos ou mais, dependendo das ligas e retries.

Não interrompa só porque demorou alguns segundos.

Depois abra:

https://SEU-USUARIO-SEU-SPACE.hf.space/

8. Como saber se o scan funcionou

Abra:

/api/state

Campos importantes:

status
model_version
summary
picks
radar
tickets
performance
providers
warnings
rejected_preview

Estados normais:

status = ok
status = degraded  # scan concluído, mas algum provider teve falha parcial
model_version = 2.2-precision

Se picks estiver vazio, veja radar e rejected_preview.

Um dia sem apostas SAFE não é considerado erro. O radar mostra as melhores leituras não aprovadas, mas elas não entram nos bilhetes nem no histórico.

9. Configurar cron-job.org

Crie um job.

URL

https://SEU-USUARIO-SEU-SPACE.hf.space/api/cron/daily

Método

POST

Horário

Sugestão:

08:00
America/Sao_Paulo

Header

Adicione:

X-Cron-Secret: SEU_CRON_SECRET

Não coloque o segredo como query string.

O endpoint responde rapidamente com HTTP 202 e o scan continua dentro do Space.

10. Frequência recomendada

Comece com 1 scan completo por dia. O endpoint de cron também bloqueia repetições muito próximas (MIN_SCAN_INTERVAL_MINUTES, padrão 180) para preservar quota.

O projeto consulta uma vez o mercado H2H por liga ativa. A lista gratuita /sports é consultada antes para evitar gastar quota com ligas fora de temporada.

Veja a quota restante em:

/api/state
→ providers.odds_api.quota.remaining

Se a quota estiver baixa, o Quota Guardian deixa de consultar novas ligas.

Não configure cron a cada 5 ou 10 minutos.

11. Backup persistente — altamente recomendado

Crie um Dataset privado no Hugging Face, por exemplo:

SEU_USUARIO/safe-bet-ai-state

Crie um token com permissão de escrita nesse Dataset.

Adicione Secrets:

HF_WRITE_TOKEN
HF_DATASET_REPO

Exemplo de valor:

HF_DATASET_REPO=SEU_USUARIO/safe-bet-ai-state

O bot passa a guardar:

state/state.json
state/history.json
state/matches.json

O matches.json é importante na v2 porque evita reconstruir toda a base histórica após cada reinício.

Se o Dataset não estiver configurado, o bot continua funcionando, mas pode precisar refazer o bootstrap quando o disco local for perdido.

12. Painel

Cada seleção mostra:

Probabilidade final.
Probabilidade conservadora.
SafeScore.
Odd de referência.
Odd justa.
Qualidade.
Confiabilidade.
Número de casas no consenso.
Dispersão de mercado.
Matching de nomes.
Dixon-Coles/Poisson.
Elo.
Forma.
Calibração forward.
Edge.

O Radar de Palpites mostra até cinco prognósticos que foram modelados, mas não passaram por todos os controles. Seus cards sempre aparecem como EM OBSERVAÇÃO — NÃO APROVADA e devem ser usados somente para acompanhar o mercado.

Odd Betano

Digite manualmente a odd encontrada na Betano.

O painel calcula:

EV = probabilidade_estimada × odd_betano - 1

A odd de referência das APIs não é tratada como se fosse a odd da sua conta.

13. Como o Risk Gate rejeita uma partida

Motivos possíveis:

histórico insuficiente
matching ambíguo
poucas casas
mercado disperso
qualidade de dados baixa
probabilidade baixa
probabilidade conservadora baixa
modelos divergentes
modelo muito distante do mercado
odd fora da faixa
preço fraco
movimento de mercado contra
seleção mudou desde o scan anterior
SafeScore baixo

Não reduza os filtros só para gerar mais palpites.

14. Bilhetes

O painel tenta criar:

SAFE        alvo ~2.5, até 3 pernas
BALANCEADO  alvo ~4.0, até 4 pernas
FREEBET     alvo ~10.0, até 4 pernas

Ele mostra se o alvo realmente foi atingido.

Também mostra probabilidade sob stress quando existem seleções da mesma competição.

A odd 10 não é tratada como “segura”; ela continua tendo risco elevado.

15. Forward tracking e calibração

O sistema guarda uma recomendação por evento.

Quando o jogo acaba:

tenta localizar o resultado na competição correta;
verifica ambos os times;
liquida win/loss;
atualiza métricas.

Depois de amostra suficiente da mesma versão do modelo, uma calibração fraca pode corrigir probabilidades futuras em no máximo ±5 pontos percentuais.

Isso evita “aprendizado” instável em poucas apostas.

16. Métricas

O painel/estado inclui:

win_rate
roi
profit_units
brier_score
log_loss
ece
calibration_gap
max_drawdown_units

Não avalie o modelo somente por taxa de acerto.

Uma taxa alta pode existir apenas porque as odds são muito baixas.

17. Testes antes de editar

Em uma máquina com Python:

pip install -r requirements-dev.txt
python -m compileall -q app tests
pytest -q

A revisão v2.2 passou:

44 passed

Também foram testados:

/
 /api/health
 /api/state

com HTTP 200.

18. Diagnóstico

`401 X-Cron-Secret inválido`

Header errado ou Secret diferente.

`configuration_error`

FOOTBALL_DATA_TOKEN ou ODDS_API_KEY ausente.

primeiro scan demorado

Pode ser o bootstrap histórico respeitando rate limit.

zero palpites

Veja o Radar e rejected_preview. O Radar informa a melhor leitura de cada jogo, mas não transforma retorno esperado negativo ou baixa confiança em aposta SAFE.

matching ambíguo

Não force o nome. A rejeição existe para impedir mistura entre equipes.

quota Odds API baixa

Reduza ligas ou frequência.

Space reiniciou

Com Dataset de backup, o cache volta automaticamente. Sem backup, o histórico pode precisar ser reconstruído.

19. Regras para manter a precisão

Não transforme SafeScore em probabilidade.
Não force dez seleções.
Não desative o market prior.
Não use fullTime para 1X2 de mata-mata quando regularTime existir.
Não misture ligas no matching.
Não considere uma única bookmaker como “consenso” no modo padrão.
Não aumente frequência sem acompanhar quota.
Não faça martingale.
Não use scraping da Betano como dependência crítica.
Mantenha model_version quando alterar regras estatísticas; ao fazer mudança grande, crie uma nova versão.
Rode os testes depois de cada alteração.