Parâmetros da API de LLM: dos campos de solicitação aos de resposta

Como é uma solicitação

O endereço do endpoint é POST https://api.apidamoxing.com/v1/chat/completions, o cabeçalho de autenticação é Authorization: Bearer <key>, e o corpo da requisição é JSON, compatível com o formato de chat completion da OpenAI. Veja primeiro uma requisição completa usando todos os campos comuns:

复制curl https://api.apidamoxing.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "你是一位耐心的天文科普作者。"},
      {"role": "user", "content": "为什么月亮总是同一面朝向地球？"}
    ],
    "temperature": 0.7,
    "top_p": 0.9,
    "max_tokens": 400,
    "stop": ["###"]
  }'

Note que o campo model aqui deve ser preenchido com uncensored, pois o serviço oferece apenas um modelo, sem opções. Você pode confirmar isso com GET /v1/models. Abaixo, explicamos campo por campo.

Ao ler o artigo inteiro, você verá que esses parâmetros se dividem em três categorias: o que "dizer" (messages, tools), como "dizer" (temperature, top_p) e "quanto dizer / quando parar" (max_tokens, stop, stream). Memorize essa classificação; ao encontrar campos desconhecidos, classifique-os primeiro e você adivinhará o uso na maioria dos casos.

messages: o “caderno” da conversa

messages é um array com role e content. Imagine um caderno de atas: o modelo lê tudo e escreve a próxima página. Ele não lembra; envie o histórico completo.

Uma dica comum: para que o modelo continue escrevendo em um certo tom, crie uma mensagem assistant e adicione ao histórico. Lembre-se de que o prompt e a saída juntos não podem ultrapassar 100.000 tokens; quanto maior o histórico, mais espaço ocupa.

Exemplo prático. Você cria um assistente de atendimento com system "Responda apenas sobre pedidos, em até três frases". Na primeira pergunta sobre entrega, e na segunda o usuário pergunta "e a devolução?". A segunda requisição deve conter sequencialmente: system, user da 1ª rodada, assistant da 1ª rodada e user da 2ª. Se faltar qualquer uma, o modelo não saberá a que "isso" se refere.

Parâmetros de amostragem: ajuste a margem de manobra

Ao gerar cada caractere, o modelo atribui escores de probabilidade a todos os candidatos e depois sorteia. Os dois parâmetros abaixo são os botões para ajustar essa regra de sorteio:

Ambos controlam o nível de aleatoriedade, apenas sob perspectivas diferentes. Ajustar ambos ao mesmo tempo dificulta identificar qual parâmetro causou a mudança, por isso recomendamos alterar apenas um de cada vez. Esses campos de amostragem padrão são repassados exatamente como enviados; a API não os modifica.

Outro exemplo numérico: suponha que as três próximas palavras tenham probabilidades de 60%, 30% e 10%. Baixar o temperature favorece o 60%, tornando a saída sempre a primeira; aumentar aproxima as probabilidades, facilitando a escolha de palavras menos comuns. Com top_p=0,9, mantemos apenas as duas primeiras (cumulativo 90%); a terceira é eliminada. Esses valores são apenas ilustrativos, não reais.

Controle de comprimento e parada: max_tokens, stop, stream

max_tokens é como o tamanho de um prato. Se o prato for pequeno, a comida será retirada antes de terminar, e o finish_reason será length. stop funciona como um sinal combinado: o cozinheiro para ao receber o sinal. stream não altera o conteúdo, apenas a forma de entrega: em vez de "servir tudo de uma vez", é "servir uma porção de cada vez", fazendo o usuário sentir que a resposta é mais rápida.

O stop tem um uso prático: ao solicitar um formato fixo como “Pergunta: ... Resposta: ...###”, definir ### como stop faz o modelo parar automaticamente no delimitador, economizando tokens e evitando respostas desnecessárias. Observe que o finish_reason será stop; para distinguir, você deve verificar o conteúdo da resposta.

tools e tool_choice: fazer o modelo "ligar" para você

O modelo não acessa dados em tempo real. O function calling funciona assim: você informa as funções disponíveis; se o modelo precisar, ele não responde diretamente, mas retorna "chame a função X com parâmetros Y". Seu programa executa e devolve o resultado; o modelo então organiza a resposta. O formato é consistente com o da OpenAI.

复制import json
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.apidamoxing.com/v1", api_key=os.environ["API_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "get_tide_time",
        "description": "查询某港口今天的高潮时刻",
        "parameters": {
            "type": "object",
            "properties": {"port": {"type": "string", "description": "港口名称"}},
            "required": ["port"],
        },
    },
}]

messages = [{"role": "user", "content": "青岛今天几点涨潮？"}]
first = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = {"port": args["port"], "high_tide": "14:20"}   # 这里换成你自己的查询
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result, ensure_ascii=False)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)
else:
    print(msg.content)

O fluxo tem duas etapas: na primeira, você obtém tool_calls; na segunda, adiciona os resultados com role: tool e faz outra requisição. Quanto mais específica for a description, mais o modelo saberá quando chamar. Os parâmetros são strings JSON; use json.loads para analisar e validar, não confie cegamente.

Campos de resposta: entendendo o “recibo” da API

Uma resposta bem-sucedida segue esta estrutura fixa:

复制{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "因为潮汐锁定……"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 38, "completion_tokens": 212, "total_tokens": 250}
}

No código, verifique primeiro o finish_reason: se for length, avise o usuário que o conteúdo foi truncado ou faça uma continuação automática; se for tool_calls, siga o fluxo de execução de funções. O papel do usage é explicado com mais detalhes sobre orçamento no artigo tokens e cobrança.

Erros comuns ao usar parâmetros

• Trate max_tokens como um "limite de entrada". Ele controla apenas a saída; a entrada é controlada por você.
• Achar que o modelo lembra de chamadas anteriores. Cada solicitação é independente; o histórico deve ser enviado por você.
• Achar que temperature=0 garante saída idêntica. A saída será mais estável, mas não necessariamente idêntica em todos os caracteres.
• Ler choices[0].message diretamente no streaming. No streaming, os blocos contêm deltas; você deve concatená-los.
• Esquecer de enviar a mensagem assistant com tool_calls na segunda etapa, causando erro na chamada subsequente.

Significados dos códigos de erro e estratégias de retry estão na documentação. Para um exemplo completo integrando esses parâmetros, consulte o artigo Criando um chatbot.