Curso
Agentes de Text-to-Query com MongoDB e LangGraph
2 h
902
A DeepSeek lançou recentemente o DeepSeek V3.1, um modelo híbrido de raciocínio em grande escala que suporta modos de resposta com e sem "pensamento" (think/non-think), ideal para análise interativa de documentos.
Neste blog, vou focar nas capacidades agentivas do DeepSeek V3.1 para entender artigos científicos. Vou explicar passo a passo como transformar qualquer PDF em um assistente de pesquisa interativo por meio de um app em Streamlit — vou mostrar:
- Como integrar o DeepSeek V3.1 via API do OpenRouter para raciocínio escalável em documentos longos
- Extração e parsing de texto em PDF para lidar com artigos acadêmicos de qualquer tamanho
- Design de um app Streamlit que permite alternar entre respostas rápidas e factuais e raciocínio profundo com evidências
- Implementação de acompanhamento de custos e medição de desempenho para cenários reais de pesquisa
- Respostas apoiadas por citações extraídas da fonte
No fim, seu app vai ficar assim:
O que é o DeepSeek V3.1?
O DeepSeek V3.1 é um modelo híbrido de Mixture-of-Experts (MoE) com 671 bilhões de parâmetros, treinado para respostas com "pensamento" (detalhadas, fundamentadas) e sem "pensamento" (factuais, concisas). Ele suporta contextos de até 128.000 tokens e é acessível via a API compatível com OpenAI do OpenRouter.
Fonte: DeepSeek
Os recursos mais importantes do DeepSeek V3.1 são:
- Suporte a longos contextos: o DeepSeek V3.1 processa com eficiência documentos extremamente longos, suportando janelas de contexto de até 128.000 tokens (mais de 100 páginas), o que o torna ideal para artigos e relatórios extensos.
- Modos duplos de raciocínio: o modelo traz dois modos de raciocínio:
- Thinking mode: fornece raciocínio detalhado, passo a passo, e cita evidências diretamente do material-fonte para análises e críticas profundas.
- Non-thinking mode: oferece respostas concisas e factuais para busca rápida de informação e Q&A ágil.
- Arquitetura híbrida mixture-of-experts: o DeepSeek V3.1 combina múltiplas sub-redes especialistas, permitindo tanto recuperação factual quanto síntese avançada no mesmo modelo.
- Workflows agentivos e com ferramentas externas: o modelo é projetado para integração com sistemas baseados em agentes e suporta uso de ferramentas externas para fluxos mais ricos e em múltiplas etapas.
- Acesso por API compatível com OpenAI: acessível via a API compatível com OpenAI do OpenRouter, o que facilita a implantação e integração para desenvolvedores.
Demo do DeepSeek V3.1: assistente para artigos científicos
Nesta seção, explico como usei o DeepSeek V3.1 para transformar qualquer artigo científico em PDF enviado pelo usuário em um assistente de pesquisa com IA.
Veja como funciona:
- Envie um PDF de artigo científico e visualize o texto extraído.
- Faça perguntas em linguagem natural sobre o artigo.
- Escolha entre “Explain in Brief” (non-think) ou “Explain in Detail” (think) como modos de resposta.
- Receba respostas na hora, com tempo de resposta, estimativas de uso de tokens/custos e citações de apoio da fonte.
Passo 1: pré-requisitos
Antes de rodar esta demo, vamos garantir que todos os pré-requisitos estejam prontos.
Passo 1.1: imports
Primeiro, garanta que você instalou os seguintes pacotes:
pip install streamlit openai pypdfEsse comando garante que você tenha as dependências básicas para a interface, tratamento de PDF e requisições à API.
Passo 1.2: configurando a chave da API do OpenRouter
O modelo DeepSeek V3.1 está disponível em várias plataformas, inclusive na API oficial da DeepSeek. Porém, usei o OpenRouter, que oferece acesso a várias chaves de API para diversos modelos e foi a opção mais econômica para esta demo. Veja como configurar uma API Key para o DeepSeek V3.1:
- Crie uma conta em https://openrouter.ai/
- Vá até a aba Models e busque por “DeepSeek V3.1”. Você também pode escolher a versão base, mas ela é treinada apenas para predição de próximo token, o que complica o prompting. Por isso, usei a versão de chat “deepseek/deepseek-chat-v3.1”.
- Role a página e clique em Create API Key. Defina um nome para a chave e um limite de crédito (opcional) e clique em Create. Guarde essa API key para usar depois.
- Depois, vá até a aba Credits e adicione seu cartão ou dados bancários. Também é possível pagar via Amazon Pay ou cripto. Para esta demo, adicionei cerca de US$ 8, o que foi suficiente.
Agora, defina sua chave de API como variável de ambiente antes de rodar o app:
export OPENROUTER_API_KEY=your_api_keyEscolhendo a API certa
A API oficial da DeepSeek é mais indicada para workloads automatizados e de alto volume.
Para a maioria dos usos de pesquisa, educação ou demonstração — incluindo este assistente de artigos em Streamlit — eu prefiro o OpenRouter por ser uma opção mais simples e flexível. Ele oferece preços globais previsíveis, sem janelas de tempo ou lógica de cache para gerenciar, sendo perfeito para análises pontuais, consultas únicas a documentos e colaboração fácil.
Observação: usar o DeepSeek V3.1 via API exige cerca de 8 GB de memória para a interface, evitando que você precise hospedar localmente o modelo gigantesco de 670B parâmetros, o que exigiria mais de 170 GB de espaço em disco e uma GPU potente.
Passo 2: configurando o app em Streamlit
Para disponibilizar o DeepSeek V3.1 em uma interface amigável, vamos usar o Streamlit como framework do app e conectá-lo ao modelo pela API compatível com OpenAI do OpenRouter.
Passo 2.1: configuração
Aqui, cobrimos o ambiente, autenticação de API e configuração básica do Streamlit.
import streamlit as stimport pypdfimport tempfilefrom openai import OpenAIimport osimport timeimport rest.set_page_config( page_title="DeepSeek V3.1 Research Assistant", layout="wide")with st.sidebar: st.title("Research Paper Assistant") st.info("Tip: Ask about the methods, findings, or reasoning for best results.")OPENROUTER_API_KEY = os.environ.get("OPENROUTER_API_KEY", "")if not OPENROUTER_API_KEY: st.warning("Add your OpenRouter API key to an environment variable.") st.stop()client = OpenAI( base_url="https://openrouter.ai/api/v1", api_key=OPENROUTER_API_KEY,)No código acima, a chamada st.set_page_config() personaliza o título e o layout da página do app Streamlit. O app recupera a chave da API do OpenRouter das variáveis de ambiente e instancia um cliente compatível com OpenAI, apontando para o endpoint do OpenRouter, garantindo que todas as chamadas ao LLM sejam roteadas e autenticadas corretamente para o DeepSeek V3.1.
Passo 2.2: funções auxiliares
Antes de construir o fluxo principal, precisamos de utilitários robustos para processamento de documentos e estimativa de recursos. Nesta etapa, definimos funções auxiliares para extrair texto de PDFs enviados, pré-visualizar o conteúdo, contar aproximadamente os tokens e estimar o custo com base nos preços do DeepSeek V3.1 no OpenRouter.
def pdf_to_text(uploaded_file): with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as tmp_file: tmp_file.write(uploaded_file.read()) tmp_path = tmp_file.name reader = pypdf.PdfReader(tmp_path) text = "" for page in reader.pages: page_text = page.extract_text() if page_text: text += page_text + "\n" return textdef preview_pdf_text(text, max_chars=600): preview = text[:max_chars] if len(text) > max_chars: preview += "\n...\n[Preview truncated]" return previewdef count_tokens(text): return max(1, int(len(text) / 4))def estimate_cost(tokens, mode="input"): if mode == "input": return tokens / 1_000_000 * 0.20 else: return tokens / 1_000_000 * 0.80Com essas funções auxiliares, nosso backend está pronto para sustentar uma interface de assistente de pesquisa escalável:
- Parsing eficiente de PDF: a função
pdf_to_text()processa PDFs com múltiplas páginas em texto simples preservando limites de página, deixando os dados prontos para entrada no LLM e para etapas posteriores. - Contagem de tokens e estimativa de custo: a função
count_tokens()fornece uma contagem aproximada de tokens para monitorar o uso da API em relação à grande janela de contexto do DeepSeek. Já aestimate_cost()traduz essa contagem em estimativas de custo em tempo real usando os preços do OpenRouter para entrada e saída, mantendo o usuário informado sobre o orçamento computacional de cada consulta. - Geração de prévia: a função
preview_pdf_text()cria prévias truncadas, permitindo verificar a integridade e relevância do conteúdo extraído antes de incorrer em custos do modelo ou atingir limites da API.
Com esses blocos prontos, podemos montar o app completo em Streamlit para Q&A agentivo com longos contextos em artigos científicos.
Passo 2.3: aplicação em Streamlit
Com os utilitários centrais prontos, vamos montar a interface principal do Streamlit, reunindo processamento de PDF, estimativa de tokens/custos, Q&A guiado pelo usuário e interação em tempo real com o DeepSeek V3.1 via OpenRouter.
st.header("Research Paper Assistant")pdf_file = st.file_uploader("Upload your research paper (PDF)", type=["pdf"])if "paper_text" not in st.session_state or st.session_state.get("last_uploaded") != pdf_file: if pdf_file is not None: with st.spinner("Extracting text from PDF..."): st.session_state.paper_text = pdf_to_text(pdf_file) st.session_state.last_uploaded = pdf_file st.success(f"PDF uploaded. Total characters extracted: {len(st.session_state.paper_text):,}") with st.expander("Preview of extracted PDF text:"): st.code(preview_pdf_text(st.session_state.paper_text), language='markdown')paper_text = st.session_state.get("paper_text")if paper_text: input_tokens = count_tokens(paper_text) st.caption(f"Estimated input tokens: {input_tokens:,} (Estimated input cost: ${estimate_cost(input_tokens):.3f})") question = st.text_area("Ask a question about this paper:", height=80, placeholder="E.g. What are the main findings?") mode = st.radio( "Select Mode", ["Explain in Brief (Non-Think)", "Explain in Detail (Think)"], horizontal=True, ) go = st.button("Get Answer", use_container_width=True) if question and go: if mode == "Explain in Brief (Non-Think)": prompt = ( f"{paper_text}\n\n" f"Question: {question}\n" "First, answer in a few sentences. Then, quote 1–2 exact sentences from the above paper that best support your answer. " "Show each quote on a new line." ) thinking_flag = False header = "Explain in Brief (Non-Think)" else: prompt = ( f"{paper_text}\n\n" f"Question: {question}\n" "First, answer in detail with reasoning and evidence. Then, quote 2–3 exact sentences from the above paper that most strongly support your answer. " "List the quotes after your answer." ) thinking_flag = True header = "Explain in Detail (Think)" with st.spinner(f"Generating answer..."): start_time = time.perf_counter() try: response = client.chat.completions.create( model="deepseek/deepseek-chat-v3.1", messages=[ {"role": "system", "content": "You are a helpful research assistant."}, {"role": "user", "content": prompt} ], max_tokens=900, extra_body={"thinking": thinking_flag}, ) answer = response.choices[0].message.content.strip() output_tokens = count_tokens(answer) except Exception as e: answer = f"Error: {e}" output_tokens = 0 end_time = time.perf_counter() elapsed_time = end_time - start_time parts = re.split(r"(?:^|\n)(Quotes?:?)", answer, flags=re.IGNORECASE) if len(parts) >= 3: main_answer = parts[0].strip() quotes = parts[2].strip() else: main_answer = answer quotes = None st.markdown(f"### {header}") st.info(f"Time taken: {elapsed_time:.2f} seconds | Output tokens: {output_tokens} (Est. output cost: ${estimate_cost(output_tokens, 'output'):.3f})") st.write(main_answer) if quotes: st.markdown("**Supporting Quotes:**") st.success(quotes)Este app em Streamlit implementa um assistente dinâmico para artigos científicos usando o DeepSeek V3.1, lidando desde a ingestão do documento até o Q&A contextual com LLM. As principais funções cobertas pelo app são:
1. Upload de PDF e cache
O usuário envia um arquivo PDF pela interface e então:
- o app verifica o
st.session_statepara ver se o arquivo é novo. Se for, extrai o texto e o armazena emsession_statejunto com a referência do upload, evitando extrações repetidas a cada interação. - Após a extração, exibe uma prévia de ~600 caracteres do documento, além de estatísticas como contagem de caracteres, tokens de entrada estimados e custo.
2. Pergunta do usuário e seleção de modo
Com o documento carregado, o usuário digita uma pergunta e escolhe entre os modos Non-think e Think; a interface adapta as instruções do prompt para cada modo:
- Non-think mode: retorna uma resposta breve com 1–2 citações de apoio do artigo.
- Think mode: retorna uma resposta detalhada e fundamentada com 2–3 citações de apoio.
3. Engenharia de prompt e chamada à API
Quando o usuário clica em "Get Answer", o app:
- monta um prompt rico em contexto, inserindo o conteúdo do artigo, a pergunta e as instruções de resposta.
- define o parâmetro
thinkingna requisição à API do OpenRouter (extra_body={"thinking": thinking_flag}), garantindo que o modelo rode no modo de raciocínio correto, sem depender apenas de temperatura. - mede tempo de inferência, tokens de saída e custo de cada resposta, exibindo tudo para transparência.
4. Pós-processamento e exibição
A resposta retornada é analisada para separar o conteúdo principal e as citações de apoio (se existirem). Em seguida, tanto a resposta quanto as citações extraídas são exibidas na interface, destacando a evidência textual exata do artigo.
Para testar por conta própria, salve o código como app.py e execute:
streamlit run app.py
