Ir para o conteúdo
Esforço de raciocínio

Esforço de raciocínio

Novo

Um modelo que raciocina retorna o seu texto de raciocínio ao lado da resposta, em um campo próprio. Nos modelos open-weight hospedados, um campo da requisição define quão profundamente o modelo raciocina antes de responder.

POST https://api.shannon-ai.com/v1/chat/completions 

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

response = client.chat.completions.create(
    model="Kimi-K3-3BIT-REAP",
    reasoning_effort="low",
    messages=[{"role": "user", "content": "Is 221 a prime number?"}],
)

message = response.choices[0].message
print("Reasoning:", getattr(message, "reasoning_content", None))
print("Answer:", message.content)
print("Reasoning tokens:", response.usage.completion_tokens_details.reasoning_tokens)

A resposta traz o texto de raciocínio em reasoning_content, a resposta em content e os tokens de raciocínio em usage:

200 JSON 
{
  "id": "chatcmpl-2a6c8e0b4d1f4a3c9e7b5d3f1a8c6e4b",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "No. 221 = 13 x 17, so it is not prime.",
        "reasoning_content": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 43,
    "total_tokens": 57,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 27}
  }
}

Quais modelos raciocinam

Modelo Retorna texto de raciocínio Aplica o campo de esforço
shannon-1.6-lite — —
shannon-1.6-pro, shannon-2-lite, shannon-2-pro, shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro, shannon-coder-1 Sim —
Todos os modelos open-weight hospedados Sim Sim

São as flags capabilities.reasoning e capabilities.reasoning_effort que GET /v1/models informa para cada id. Uma resposta traz texto de raciocínio apenas quando o modelo produziu algum. Modelos e preços

Definindo o esforço

Cada endpoint tem a sua própria grafia para o esforço. Todas selecionam um dos mesmos quatro níveis.

Campo Tipo Padrão Descrição Aplicado por
reasoning_effort string high /v1/chat/completions. Quão profundamente o modelo raciocina antes de responder: off, low, medium ou high. Modelos open-weight hospedados
reasoning object | string /v1/chat/completions. O mesmo valor como {"effort": "low"} ou como uma string simples. Quando os dois campos são enviados, vale reasoning_effort. Modelos open-weight hospedados
reasoning.effort string high /v1/responses. Escrito como o objeto {"effort": "low"}. Modelos open-weight hospedados
thinking object /v1/messages. {"type": "enabled", "budget_tokens": n} ou {"type": "disabled"}. O orçamento seleciona um dos níveis; veja a tabela mais abaixo. Modelos open-weight hospedados 
{
  "model": "Kimi-K3-3BIT-REAP",
  "reasoning_effort": "low",
  "messages": [{"role": "user", "content": "Is 221 a prime number?"}]
}
Valor Também aceito Efeito
off none, minimal Sem raciocínio. A resposta não traz texto de raciocínio.
low Raciocínio breve.
medium default Profundidade média.
high max O nível mais profundo. É o nível de uma requisição que não envia valor.
  • Os valores são lidos sem diferenciar maiúsculas de minúsculas.
  • O valor default significa medium. Omitir o campo significa high.
  • Os modelos Shannon (shannon-*) definem a própria profundidade em cada requisição; GET /v1/models informa reasoning_effort: false para eles.

O orçamento de raciocínio em /v1/messages

Em /v1/messages, o campo thinking seleciona o nível. budget_tokens escolhe um dos níveis acima; não é um limite de tokens próprio. adaptive é lido como enabled.

Você envia Nível
{"type": "disabled"} off
{"type": "enabled", "budget_tokens": n} com n até 2,048 low
n de 2,049 a 8,192 medium
Um n maior, ou enabled sem budget_tokens high
Sem campo thinking high

Onde o texto de raciocínio chega

O texto de raciocínio é sempre separado da resposta. Cada formato tem o seu próprio lugar para ele:

Endpoint Sem stream Com stream
/v1/chat/completions choices[0].message.reasoning_content: uma string, ou null quando o modelo não produziu nenhum. Chunks com choices[0].delta.reasoning_content, antes dos chunks com delta.content.
/v1/responses Um item de output {"type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} antes do item message. Sem item quando não há raciocínio. response.output_item.added com um item reasoning, depois eventos response.reasoning_summary_text.delta e um response.reasoning_summary_text.done.
/v1/messages Um primeiro bloco de conteúdo {"type": "thinking", "thinking": "…"}, depois o bloco text. Sem bloco thinking quando não há raciocínio. Um bloco de conteúdo thinking: content_block_start, eventos content_block_delta com thinking_delta, content_block_stop. O bloco de texto vem em seguida. 
{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "No. 221 = 13 x 17, so it is not prime.",
        "reasoning_content": "Try small primes. 221 / 13 = 17, so 221 = 13 x 17."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 43,
    "total_tokens": 57,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 27}
  }
}

Onde procurar, por modelo:

Modelos Onde o texto chega
Modelos open-weight hospedados Em todos os endpoints, com ou sem stream. Uma requisição com esforço off, ou com response_format / text.format, é respondida sem texto de raciocínio.
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro Em todos os endpoints, com ou sem stream, sempre que o modelo produziu texto de raciocínio.
shannon-2-lite, shannon-2-pro /v1/chat/completions, sem stream: em message.reasoning_content. Com stream, em uma requisição sem tools nem response_format: o stream traz linhas de comentário : thinking enquanto o modelo raciocina, depois os chunks da resposta. /v1/messages, com stream: um bloco thinking antes do bloco de texto.
shannon-1.6-pro, shannon-coder-1 Em respostas com stream e em respostas a requisições que trazem tools, sempre que o modelo produziu texto de raciocínio.

Em /v1/responses, uma resposta sem stream traz o item reasoning para a família Shannon 3 e para os modelos open-weight hospedados.

Lendo um stream

Em um stream, o texto de raciocínio vem primeiro, em deltas próprios, e a resposta vem depois. Exiba ou armazene os dois separadamente:

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

stream = client.chat.completions.create(
    model="Kimi-K3-3BIT-REAP",
    reasoning_effort="medium",
    stream=True,
    messages=[{"role": "user", "content": "Is 221 a prime number?"}],
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        print(reasoning, end="", flush=True)      # the reasoning text comes first
    if delta.content:
        print(delta.content, end="", flush=True)  # then the answer

O primeiro chunk de um modelo open-weight hospedado, de raciocínio ou de resposta, também traz delta.role: "assistant". Streaming

Tokens de raciocínio e faturamento

Nos modelos open-weight hospedados, os tokens de raciocínio são tokens de saída: são faturados ao preço de saída do modelo, e a contagem de saída já os inclui. usage mostra aqui a parcela de raciocínio:

Endpoint Campo Observação
/v1/chat/completions usage.completion_tokens_details.reasoning_tokens Já incluído em completion_tokens.
/v1/responses usage.output_tokens_details.reasoning_tokens Já incluído em output_tokens.
/v1/messages usage.output_tokens Raciocínio e resposta juntos. Este formato não tem contagem separada.
  • Nos modelos open-weight hospedados, max_tokens limita o texto da resposta. Os tokens de raciocínio não contam para esse limite.
  • Como o raciocínio é faturado como saída, o nível de esforço também é uma configuração de custo: off não produz tokens de raciocínio.
  • Os modelos Shannon informam prompt_tokens, completion_tokens e total_tokens (input_tokens e output_tokens em /v1/messages) sem parcela de raciocínio, e cobram um preço único por token. Modelos e preços

O raciocínio na próxima requisição

Você não precisa enviar o raciocínio de volta. Um bloco thinking ou um item reasoning na conversa que você envia não é repassado ao modelo, então um turno do assistente pode voltar com ou sem ele. Um bloco thinking tem os dois campos type e thinking; não tem signature.

Erros

Status Tipo Mensagem Quando
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Um modelo open-weight hospedado recebeu um valor fora da lista, por exemplo xhigh. Nada é descontado do seu saldo.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … reasoning_effort não é uma string.

Os erros de autenticação, de saldo e do servidor são os mesmos de qualquer requisição. Tratamento de erros