poc-grok-websearch/README.md

Grok Web Search via OCI

POC de chatbot com interface JavaScript e backend Python/FastAPI. Usa Grok (padrão xai.grok-4.3, configurável por OCI_MODEL) pela OCI Generative AI e habilita a ferramenta nativa web_search na Responses API. A aplicação chama exclusivamente o endpoint OCI.

Estrutura

.
├── app.py                          # Backend e autenticação
├── static/
│   ├── index.html                  # Interface e estilos
│   └── app.js                      # Chat, histórico e citações
├── requirements.txt
├── requirements-test.txt           # TestClient para matriz de modelos
├── Dockerfile
├── .dockerignore
├── .gitignore
├── .env.example                    # Variáveis sem credenciais
├── validate.py                     # Validação REST com inferência real
├── test_models.py                  # Matriz de modelos pela mesma aplicação
└── evidence/
    ├── RELATORIO.md                # Resultados da POC
    ├── validation-summary.json     # Evidências selecionadas
    └── grok-websearch-models.json   # Matriz de compatibilidade datada

Configuração

Requer Python 3.12 ou Docker, uma chave OCI Generative AI e um projeto GenAI ativo na região us-chicago-1, com permissão para inferência e Responses API.

Na raiz do repositório:

cp .env.example .env
chmod 600 .env

Preencha .env:

Variável	Finalidade
OCI_BASE_URL	https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/v1
OCI_MODEL	Modelo Grok; padrão xai.grok-4.3
OCI_API_KEY	Chave OCI Generative AI
OCI_PROJECT_ID	Identificador de projeto ativo em Chicago
APP_PASSWORD	Senha forte para o usuário poc
APP_BASE_URL	URL pública ou local, com o prefixo de publicação; usada por validate.py

.env é ignorado pelo Git e pelo build Docker. As credenciais OCI ficam no backend. O histórico de conversa permanece na página e é reenviado a cada turno.

Executar localmente

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
set -a
. ./.env
set +a
uvicorn app:app --host 127.0.0.1 --port 8080

Abra http://localhost:8080/. A autenticação solicita usuário poc e a senha definida em APP_PASSWORD.

Com Docker:

docker build -t poc-grok-websearch:1 .
docker run -d --name poc-grok-websearch --restart unless-stopped \
  --env-file .env -p 127.0.0.1:8080:8080 poc-grok-websearch:1 \
  uvicorn app:app --host 0.0.0.0 --port 8080

Publicar na VM

Copie o repositório e configure .env na VM. Faça o build com o Dockerfile e execute o container em uma rede acessível ao proxy reverso. Publique por HTTPS, encaminhando para a porta interna 8080.

O comando padrão da imagem configura --root-path /grok-poc. Para esse modo, publique em /grok-poc/ e remova o prefixo /grok-poc no proxy antes de encaminhar ao backend. Para publicação na raiz do domínio, use o comando uvicorn sem --root-path, como no exemplo Docker acima. Ajuste APP_BASE_URL para a URL completa, incluindo o prefixo quando usado.

Basic Auth requer HTTPS fora do ambiente local. A POC limita a concorrência a duas inferências, mas não impõe limite financeiro por usuário nem rate limiting por cliente.

Arquitetura

flowchart LR
    UI[Browser / JavaScript] -->|HTTPS + Basic Auth| Proxy[Proxy reverso na VM]
    Proxy --> API[Python / FastAPI]
    API -->|Bearer OCI + OpenAI-Project| OCI[OCI Chicago /v1/responses]
    OCI --> Grok[xai.grok-4.3 + web_search]
    Grok --> Web[Pesquisa e abertura de páginas]

O backend envia tools: [{"type":"web_search"}], store:false e limite de 2400 tokens de saída. O modelo decide quando pesquisar e pode reformular consultas. Não há fallback para outros provedores nem motor de busca externo implementado pela aplicação.

A Oracle informa que os modelos Grok acessados pela OCI são hospedados externamente pela xAI. A aplicação autentica e chama exclusivamente OCI. Veja a documentação Oracle.

Nos testes de 14/10/2026, /openai/v1/responses rejeitou web_search para Grok; /v1/responses e /20231130/actions/v1/responses funcionaram com um projeto ativo de Chicago. A aplicação usa /v1/responses.

Modelos com web_search confirmado em 14/10/2026

Teste da mesma rota /api/chat em processos locais isolados via FastAPI TestClient, com inferência real na OCI us-chicago-1, endpoint /v1/responses, projeto ativo e tools: [{"type":"web_search"}]. Não foram chamadas APIs diretas da xAI. A implantação pública original foi validada com Grok 4.3; esta matriz usa a aplicação local para variar os modelos sem interromper a VM.

Modelo solicitado e retornado	Busca nativa	HTTP app/OCI	Buscas concluídas	Citações	Tempo (s)
xai.grok-4.20-0309-non-reasoning	Confirmado	200/200	2	1	3.62
xai.grok-4.20-0309-reasoning	Confirmado	200/200	1	2	14.80
xai.grok-4.20-non-reasoning	Confirmado	200/200	2	1	3.22
xai.grok-4.20-reasoning	Confirmado	200/200	2	1	17.09
xai.grok-4.3	Confirmado	200/200	2	1	9.24
xai.grok-4.6	Confirmado	200/200	1	1	35.17
xai.grok-4.7	Confirmado	200/200	3	1	12.97

Critério de confirmação: HTTP 200, pelo menos um evento web_search_call com ação search e status completed, fontes não vazias e citações estruturadas. HTTP 200 isolado não comprova a execução de busca.

Foram sete chamadas, sem retries, com até duas inferências simultâneas e 2400 tokens de saída por chamada. Todos os modelos retornaram exatamente o identificador solicitado. Os testes cobrem os sete modelos de texto Grok do catálogo local; Voice Agent, Multi-Agent e outros identificadores não foram testados. O resultado vale para esta data, região, endpoint e permissões; não confirma todas as regiões ou interfaces OCI. A validação da busca não equivale à verificação independente de todas as notícias retornadas.

Os tempos são observações de uma chamada por modelo, sob concorrência limitada, e não constituem benchmark. Consumo agregado: 76.374 tokens (69.948 de entrada e 6.426 de saída), com 13 ferramentas contabilizadas pelo serviço. cost_in_usd_ticks foi preservado sem conversão financeira.

Para escolher um modelo, defina OCI_MODEL no .env e reinicie o serviço. O padrão continua xai.grok-4.3; /health e o indicador da UI refletem a configuração.

Para reproduzir a matriz (sete chamadas pagas):

. .venv/bin/activate
pip install -r requirements-test.txt
set -a
. ./.env
set +a
python test_models.py

Para testar somente um modelo:

python test_models.py --models xai.grok-4.7

O script salva respostas brutas localmente em ./evidence/model-tests-raw/ (ignoradas pelo Git) e um resumo da matriz, sem credenciais nem identificadores de projeto. Execuções parciais na mesma data preservam os resultados dos demais modelos já testados. As versões do runtime usado na matriz original estão no JSON; a reprodução instala as dependências fixadas do aplicativo.

Referências do fornecedor: Grok 4.20, Grok 4.6 e Grok 4.7. A confirmação nesta tabela vem dos testes de execução.

API REST

POST /api/chat com HTTP Basic. Na publicação com prefixo, use POST /grok-poc/api/chat.

{"message":"Pesquise uma notícia publicada hoje e cite fonte e data.","history":[]}

history aceita até 12 turnos com role igual a user ou assistant; cada conteúdo tem limite de 8000 caracteres. A resposta contém answer, citations, web_search_calls, usage, response_id, model, timestamp, seconds e raw_response.

Exemplo local; curl solicita a senha:

curl --user poc http://localhost:8080/api/chat \
  -H 'Content-Type: application/json' \
  --data '{"message":"Pesquise uma notícia publicada hoje e cite fonte e data."}'

GET /health retorna o estado do serviço sem autenticação. A página, JavaScript e chat exigem autenticação.

Validar

Com o serviço em execução e .env preenchido:

. .venv/bin/activate
set -a
. ./.env
set +a
python validate.py

O script faz uma chamada paga de inferência sobre notícia de hoje, verifica resposta, eventos de busca e citações, além dos códigos HTTP de autenticação e validação. Salva resultados locais em ./evidence/, ignorados pelo Git. A confirmação da data e do conteúdo da fonte requer conferência independente; o script não a automatiza.

Na execução original, o REST retornou HTTP 200 em 36,12 segundos, com duas buscas concluídas e uma abertura de página após uma tentativa inicial falhar. A fonte foi acessada independentemente e mostrou publicação em 14/10/2026 às 08:17. Desktop e celular passaram nas verificações de JavaScript e layout. A renderização foi verificada com uma fixture da resposta REST real.

Consulte o relatório e o resumo estruturado. Apenas evidências selecionadas são compartilhadas; credenciais, dados administrativos OCI, respostas brutas, cópias integrais das fontes e scripts específicos da infraestrutura ficam locais.