Estudo de LangChain

#ia #llm #estudo #fonte_de_conhecimento

Um modelo simples para cada nota:

  • Definição em uma frase
  • Por que importa (o que quebra ou muda se você ignorar)
  • Exemplo curto ou trecho de código
  • Notas relacionadas
  • Perguntas em aberto
  • Fontes

Modelo de Linguagem Grande (LLM)

1. Definição

Um modelo de linguagem grande é um modelo probabilístico treinado com enormes quantidades de texto para prever o próximo token de uma sequência. "Grande" se refere ao número de parâmetros que ele contém, normalmente bilhões ou mais.

2. Por que importa

  • Tudo o que um modelo faz (responder, resumir, programar) vem da repetição: prever o próximo token, acrescentá-lo e repetir.
  • LLMs são uma tecnologia de uso geral que transformou a forma como as pessoas interagem com computadores.

3. Exemplo

Prompt: "The capital of France is"

Next-token probabilities (illustrative):
- " Paris"   → 0.97
- " a"       → 0.01
- " located" → 0.005

The model samples one token (usually " Paris"), appends it, and predicts again.

API call that produces this behavior:

    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=50,
        messages=[{"role": "user", "content": "The capital of France is"}],
    )

4. Notas relacionadas

5. Perguntas em aberto

  1. Como os parâmetros funcionam? Eu poderia procurar um exemplo simples para ver como eles são.

6. Fontes


Tokens

1. Definição

É a unidade básica de texto, que pode ser uma palavra inteira ou parte de uma.

2. Por que importa

  • Tokens são a unidade com que os LLMs trabalham.
  • Janelas de contexto são medidas em tokens.
  • O preço das APIs é cobrado por token, então eles determinam o custo.

3. Exemplo

Text: "Tokenization is unbelievable!"

One possible split (exact splits vary by tokenizer):

    ["Token", "ization", " is", " un", "believ", "able", "!"]

That's 7 tokens for 4 words. Common words are usually one token, while
longer or rarer words get broken into pieces.

Checking real counts with the API:

    count = client.messages.count_tokens(
        model="claude-sonnet-5-5",
        messages=[{"role": "user", "content": "Tokenization is unbelievable!"}],
    )

    print(count.input_tokens)

Experiment: run the same sentence in English and in another language, and
compare input_tokens. The non-English version will often use more.

4. Notas relacionadas

5. Perguntas em aberto

  • Por que os tokenizadores dividem as palavras em pedaços em vez de usar palavras inteiras?

6. Fontes


Janela de contexto

1. Definição

É a quantidade máxima de texto, medida em tokens, que um LLM consegue manter e consultar enquanto gera uma resposta.

2. Por que importa

  • Entrada e saída dividem a mesma janela. Um prompt longo, que ocupa quase toda a janela de contexto, pode deixar pouco espaço para a saída, que pode acabar cortada.
  • Ela orienta decisões de design, porque obriga você a encontrar formas de recuperar só o que importa.

3. Exemplo

Say a model has a 10,000-token context window (illustrative number).

| Turn | Input sent (history + new msg) | Reply | Total used |
|------|-------------------------------|-------|-----------|
| 1    | 200                           | 300   | 500       |
| 2    | 800                           | 300   | 1,100     |
| 3    | 1,400                         | 300   | 1,700     |

Each turn's input includes all previous turns, so usage climbs steadily. Keep
going and eventually the input plus the reply won't fit.

In code, the growth looks like this:

    messages = []

    def chat(user_text):
        messages.append({"role": "user", "content": user_text})
        response = client.messages.create(
            model="claude-sonnet-5-5",
            max_tokens=500,
            messages=messages,          # the whole history, every time
        )
        reply = next(
            (block.text for block in response.content if block.type == "text"), ""
        )
        messages.append({"role": "assistant", "content": response.content})
        print(response.usage.input_tokens)   # watch this number grow
        return reply

Experiment: call chat() five times and print input_tokens each time.

4. Notas relacionadas

5. Perguntas em aberto

  • Que estratégias lidam com conversas que ultrapassam a janela (resumir, truncar, recuperação)?
  • Por que os modelos às vezes deixam passar detalhes no meio de entradas longas?

6. Fontes


Temperatura

1. Definição

Um parâmetro que controla a aleatoriedade do texto que um LLM gera. Valores mais baixos deixam a saída previsível e consistente, enquanto valores mais altos tornam as respostas mais criativas e variadas.

2. Por que importa

  • Ela controla o quão consistentes as respostas são. Use uma temperatura baixa para tarefas com uma resposta certa, e uma alta para brainstorming ou escrita criativa.
  • Mesmo com temperatura 0, não há garantia de respostas idênticas: a saída de um LLM não é totalmente determinística.
  • Os modelos atuais do Claude não aceitam o parâmetro temperature, embora outros provedores ainda possam oferecê-lo.

3. Exemplo

Prompt: "The sky is"

Next-token probabilities (illustrative):
- " blue"  → 0.70
- " clear" → 0.15
- " gray"  → 0.10
- " falling" → 0.05

Effect of temperature, taking these as the probabilities at 1.0:
- Below 1.0: the distribution sharpens, so " blue" dominates.
- At 1.0: the probabilities stay as listed.
- Above 1.0: the distribution flattens, so " falling" becomes a real possibility.

A small simulation, with no API needed:

    probs = {" blue": 0.70, " clear": 0.15, " gray": 0.10, " falling": 0.05}

    for t in [0.2, 0.7, 1.0, 2.0]:
        weights = {token: p ** (1 / t) for token, p in probs.items()}
        total = sum(weights.values())
        print(t, {token: round(w / total, 2) for token, w in weights.items()})

Output:

    0.2 {' blue': 1.0, ' clear': 0.0, ' gray': 0.0, ' falling': 0.0}
    0.7 {' blue': 0.84, ' clear': 0.09, ' gray': 0.05, ' falling': 0.02}
    1.0 {' blue': 0.7, ' clear': 0.15, ' gray': 0.1, ' falling': 0.05}
    2.0 {' blue': 0.47, ' clear': 0.22, ' gray': 0.18, ' falling': 0.13}

Experiment: add 0.01 and 10 to the list, and see what happens at both extremes.

4. Notas relacionadas

  • LLM: o comportamento que ela altera
  • Tokens: ela atua sobre as probabilidades do próximo token
  • Chamada de API: os provedores que ainda a oferecem a recebem como parâmetro da chamada

5. Perguntas em aberto

  • Qual a diferença entre top-p, top-k e temperatura, e dá para combiná-los?
  • Por que a temperatura 0 não é totalmente determinística?

6. Fontes


Mensagens de sistema / usuário / assistente

1. Definição

Mensagens são os turnos, cada um identificado por um papel, que compõem uma conversa com um LLM.

  • Mensagens de sistema dão instruções gerais e contexto para o comportamento do assistente.
  • Mensagens de usuário contêm as perguntas ou prompts específicos dos usuários.
  • Mensagens de assistente representam as respostas geradas pelo modelo com base nas mensagens anteriores de sistema ou de usuário.

2. Por que importa

  • Papéis são uma ferramenta de design.
  • Os três papéis contam para a janela de contexto.

3. Exemplo

Same question, with and without a system message:

    # No system message
    messages=[{"role": "user", "content": "What is a token?"}]

    # With a system message
    system="You are a teacher for beginners. Answer in two sentences, no jargon."
    messages=[{"role": "user", "content": "What is a token?"}]

A multi-turn conversation, where I include the assistant's previous reply:

    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=300,
        system="You are a teacher for beginners. Answer in two sentences, no jargon.",
        messages=[
            {"role": "user", "content": "What is a token?"},
            {"role": "assistant", "content": "A token is a small chunk of text the model reads and writes."},
            {"role": "user", "content": "Why does it matter for cost?"},
        ],
    )

Experiment: ask the third question alone, then with the full history. Compare the answers. Without the history, the model doesn't know what "it" refers to.

4. Notas relacionadas

5. Perguntas em aberto

  • Quanto a mensagem de sistema realmente muda o comportamento, em comparação com colocar o mesmo texto na primeira mensagem de usuário?

6. Fontes


Chamada de API

1. Definição

Uma chamada de API a um modelo é uma requisição HTTP em que você envia suas mensagens e configurações para um servidor, e ele devolve a resposta do modelo.

2. Por que importa

  • É assim que qualquer projeto interage com LLMs.
  • Cada requisição não guarda estado, então você precisa reenviar a conversa inteira toda vez.

3. Exemplo

Request (curl):

    curl https://api.anthropic.com/v1/messages \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{
        "model": "claude-sonnet-5-5",
        "max_tokens": 1024,
        "system": "You are a helpful assistant that explains things simply.",
        "messages": [
          {"role": "user", "content": "What is a token?"}
        ]
      }'

Same call in Python:

    import anthropic

    client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=1024,
        system="You are a helpful assistant that explains things simply.",
        messages=[{"role": "user", "content": "What is a token?"}],
    )

    text = next(
        (block.text for block in response.content if block.type == "text"), ""
    )

    print(text)
    print(response.stop_reason)
    print(response.usage.input_tokens, response.usage.output_tokens)

Trimmed response:

    {
      "id": "msg_01...",
      "role": "assistant",
      "content": [{"type": "text", "text": "A token is a small chunk of text..."}],
      "stop_reason": "end_turn",
      "usage": {"input_tokens": 25, "output_tokens": 80}
    }

Experiment: set max_tokens to 10 and watch stop_reason change. Then deliberately use a wrong API key and read the error that comes back.

4. Notas relacionadas

5. Perguntas em aberto

  • O que meu código deve fazer quando uma chamada falha ou atinge um limite de taxa?

6. Fontes


Saída estruturada

1. Definição

Uma técnica para fazer o modelo responder em um formato previsível e legível por máquina, normalmente JSON.

2. Por que importa

  • É o formato em que se deve confiar ao salvar em um banco de dados, enviar para uma API etc.

3. Exemplo

Same fact, two possible free-text replies:

    Ana is 31 years old.
    The person's name is Ana, and she's 31.

With structured output, the shape is always the same:

    {"name": "Ana", "age": 31}

The native way, using a Pydantic model as the schema:

    from pydantic import BaseModel

    class Person(BaseModel):
        name: str
        age: int

    response = client.messages.parse(
        model="claude-sonnet-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Ana is 31 years old."}],
        output_format=Person,
    )

    print(response.parsed_output)  # name='Ana' age=31

Experiment: drop the schema, ask for JSON in the prompt instead, and run json.loads() on the reply a few times. See how often it breaks.

4. Notas relacionadas

  • Ferramentas: ferramentas também usam um schema, que descreve os argumentos de uma função, e não a resposta
  • Chamada de API: o schema vai junto com a requisição
  • Runnable / LCEL: parsers de saída transformam a resposta em dados, como uma etapa de uma chain

5. Perguntas em aberto

  • O que acontece quando a saída segue o schema, mas os valores estão errados?

6. Fontes


Ferramentas

1. Definição

Uma forma de deixar seu modelo pedir ao seu código que execute algo e usar o resultado na resposta.

É um mecanismo que permite a um modelo de IA gerar requisições estruturadas, normalmente em JSON, para invocar funções ou APIs externas. Há duas formas de invocar uma ferramenta:

  • Invocação automática de ferramentas: o LLM decide se faz sentido chamar uma ferramenta ou não. Essa é a escolha padrão.
  • Invocação forçada de ferramentas: o desenvolvedor do sistema configura o modelo para sempre usar determinadas ferramentas. Isso é ideal para pipelines determinísticos, como a extração de dados estruturados. Alguns modelos, incluindo o Claude Sonnet 5.5 e o Opus 5.5, não oferecem suporte a isso.

2. Por que importa

  • LLMs preveem texto plausível, então não são confiáveis para cálculos exatos.
  • Usar ferramentas amplia o poder e a utilidade do modelo.
  • O modo de invocação define se é o modelo ou o desenvolvedor quem escolhe quando uma ferramenta é executada.

3. Exemplo

The model doesn't run anything itself. It asks, my code runs the function, and I send back the result:

    tools = [{
        "name": "multiply",
        "description": "Multiply two numbers.",
        "input_schema": {
            "type": "object",
            "properties": {"a": {"type": "number"}, "b": {"type": "number"}},
            "required": ["a", "b"],
        },
    }]
    messages = [{"role": "user", "content": "What is 48213 * 9177?"}]

    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=300,
        tools=tools,
        messages=messages,
    )

    # response.stop_reason is "tool_use": the model is asking for the function
    call = next(block for block in response.content if block.type == "tool_use")
    result = call.input["a"] * call.input["b"]  # my code does the math

    messages.append({"role": "assistant", "content": response.content})
    messages.append({
        "role": "user",
        "content": [{"type": "tool_result", "tool_use_id": call.id, "content": str(result)}],
    })

    final = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=300,
        tools=tools,
        messages=messages,
    )
    text = next(block.text for block in final.content if block.type == "text")
    print(text)

Experiment: ask the same question without the tool and compare the answer with the exact result.

Veja mais exemplos no artigo do n8n LLM Tool Calling: How It Works and How To Implement It.

4. Notas relacionadas

5. Perguntas em aberto

  • Como o modelo decide qual ferramenta chamar, e o que acontece se ele escolher a errada?
  • Qual a diferença entre passar uma função Python diretamente e usar o decorador @tool?

6. Fontes


Runnable / LCEL: compondo etapas

1. Definição

Um Runnable é a interface padrão do LangChain para um componente, e a LangChain Expression Language (LCEL) é a sintaxe | para compor Runnables em uma chain. Prompts, modelos e parsers de saída são todos Runnables.

2. Por que importa

  • Todos os processos são como pipelines. Compor essas etapas representa um pipeline de ponta a ponta em um contexto de IA.

3. Exemplo

A three-step chain, composed with the | operator:

    from langchain_anthropic import ChatAnthropic
    from langchain_core.output_parsers import StrOutputParser
    from langchain_core.prompts import ChatPromptTemplate

    prompt = ChatPromptTemplate.from_template("Explain {topic} in one sentence.")
    model = ChatAnthropic(model="claude-sonnet-5-5")
    parser = StrOutputParser()

    chain = prompt | model | parser

    print(chain.invoke({"topic": "tokens"}))

Each step's output is the next step's input:

    {"topic": "tokens"} → prompt → messages → model → AI message → parser → string

Experiment: remove the parser from the chain and print the result. It's now an AI message object instead of a string.

4. Notas relacionadas

5. Perguntas em aberto

  • O que a LCEL me oferece que uma função Python comum não oferece?

6. Fontes


O loop do agente

1. Definição

O loop do agente é uma série de etapas em que o modelo decide repetidamente se chama uma ferramenta ou dá a resposta final, e continua no loop até produzir uma resposta final ou até uma condição de parada ser atingida.

2. Por que importa

  • Agentes resolvem problemas em que as etapas não podem ser conhecidas de antemão. Se as etapas forem fixas e previsíveis, um agente pode ser a escolha errada, e o mesmo vale para tarefas de baixo valor.

3. Exemplo

Veja os exemplos na página Agents do LangChain.

4. Notas relacionadas

5. Perguntas em aberto

  • N/A

6. Fontes

  • Agents, documentação do LangChain