Este documento descreve como chamar o service de inferência do modelo Kimi implantado no Alibaba Cloud Model Studio.
kimi-k3.1-pro suporta OpenAI Chat Completions, OpenAI Responses, Anthropic Messages e a API nativa DashScope.
Os endpoints de service são específicos por região. Configure a URL base correta para sua região.
- OpenAI compatible
- DashScope
- Anthropic-compatible
base_url abaixo também se aplicam a chamadas OpenAI Responses. Em requisições HTTP, acrescente /responses ao base_url, como em POST {base_url}/responses.- US (Virginia)
- Germany (Frankfurt)
- Singapore
- Japan (Tokyo)
- China (Beijing)
- China (Hong Kong)
base_url para chamadas SDK é: https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1URL da requisição HTTP: POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions{WorkspaceId} pelo seu workspace ID real.
Pré-requisitos: Você deve obter uma API key e configurá-la como variável de ambiente. Se usar o SDK, você deve instalar o SDK.
Primeiros passos
Os exemplos a seguir usam apenas entrada de texto. Para exemplos multimodais, consulte chamada multimodal.
- OpenAI compatible
- DashScope
- Anthropic compatible
- Python
- Node.js
- HTTP
Resposta
Chamadas multimodais
Os modelos kimi-k3.1-pro, kimi-k3, kimi-k2.7-code, kimi-k2.6 e kimi-k2.5 suportam entrada multimodal e saída de texto. kimi-k3.1-pro e kimi-k3 suportam apenas entrada de texto e imagem, não entrada de vídeo; kimi-k2.7-code, kimi-k2.6 e kimi-k2.5 processam simultaneamente texto, imagens ou vídeo. Use o parâmetro enable_thinking para ativar o modo de raciocínio. Os exemplos a seguir mostram como utilizar esse recurso.
Ativar ou desativar o modo de raciocínio
Os modelos kimi-k2.6 e kimi-k2.5 são híbridos de raciocínio. Eles podem responder após raciocinar ou responder diretamente. Utilize o parâmetro enable_thinking para controlar a ativação do modo de raciocínio:
true: Ativa o modo de raciocíniofalse(padrão): Desativa o modo de raciocínio
kimi-k2.7-code opera exclusivamente com raciocínio: o modo de raciocínio está sempre ativado (enable_thinking tem como padrão true e não pode ser desativado), e preserve_thinking tem como padrão true.
kimi-k3.1-pro e kimi-k3 ativam o pensamento por padrão (enable_thinking=true). Você pode definir como false para desativar o pensamento, mas é recomendável mantê-lo ativado. Para kimi-k3.1-pro, desativar o pensamento degrada significativamente a qualidade da saída; portanto, é altamente recomendável mantê-lo ativado. Ambos os modelos preservam por padrão o reasoning_content histórico fornecido pelo cliente. Recomendamos reenviar o reasoning_content completo das mensagens históricas do assistente em solicitações de múltiplos turnos.
O kimi-k2.6 permite transmitir o processo de raciocínio em conversas de múltiplos turnos por meio do parâmetro preserve_thinking. Para mais informações, consulte Passar o processo de raciocínio.
Os exemplos abaixo demonstram como usar uma URL de imagem e ativar o modo de raciocínio. O exemplo principal ilustra a entrada de uma única imagem, enquanto o código comentado serve como exemplo para entrada de múltiplas imagens.
- OpenAI compatible
- DashScope
Compreensão de vídeo
- Video file
- Image list
-
fps: Controla a frequência de extração de quadros. O intervalo entre os quadros extraídos é de
1/fpssegundos. O valor deve estar no intervalo de [0.1, 10]. O valor padrão é 2.0.- Para cenas com muito movimento: Defina um valor de fps mais alto para capturar mais detalhes.
- Para vídeos estáticos ou longos: Defina um valor de fps mais baixo para melhorar a eficiência do processamento.
- max_frames: Especifica o número máximo de quadros a serem extraídos de um vídeo. O valor padrão e máximo é 2000. Se o número de quadros calculado a partir do valor de fps exceder esse limite, o sistema extrairá quadros uniformemente para permanecer dentro do limite de max_frames. Este parâmetro está disponível apenas quando você usa o DashScope SDK.
- OpenAI compatible
- DashScope
Ao passar um arquivo de vídeo para o modelo usando o OpenAI SDK ou uma requisição HTTP, defina o parâmetro"type"na mensagem do usuário como"video_url".
Passar um arquivo local
Os exemplos a seguir mostram como passar um arquivo local. A API compatível com OpenAI suporta apenas codificação Base64, enquanto o DashScope suporta tanto codificação Base64 quanto caminhos de arquivo.
- OpenAI compatible
- DashScope
Limitações de arquivos
- Image limitations
- Video limitations
-
Resolução da imagem:
- Tamanho mínimo: Largura e altura devem exceder
10pixels cada. - Proporção: A razão entre o lado mais longo e o mais curto não deve exceder
200:1. - Resolução máxima: O máximo recomendado é
8K(7680x4320). Resoluções maiores podem causar timeouts na chamada da API devido ao tamanho grande dos arquivos ou transferências de rede lentas.
- Tamanho mínimo: Largura e altura devem exceder
-
Formatos de imagem suportados
-
Os seguintes formatos são suportados para resoluções abaixo de 4K
(3840x2160):Formato de imagem
Extensão de arquivo
Tipo MIME
BMP
.bmp
image/bmp
JPEG
.jpe, .jpeg, .jpg
image/jpeg
PNG
.png
image/png
TIFF
.tif, .tiff
image/tiff
WEBP
.webp
image/webp
HEIC
.heic
image/heic
-
Para resoluções entre
4K(3840x2160)e8K(7680x4320), apenas JPEG, JPG e PNG são suportados.
-
Os seguintes formatos são suportados para resoluções abaixo de 4K
-
Tamanho da imagem:
- Ao fornecer uma imagem via URL pública ou caminho local, seu tamanho não deve exceder
10 MB. - Ao usar codificação Base64, a string codificada não deve exceder
10 MB.
Para compactar um arquivo, consulte How to compress an image or video to meet the size limit .
- Ao fornecer uma imagem via URL pública ou caminho local, seu tamanho não deve exceder
- Número de imagens suportadas: Ao fornecer várias imagens, o número total de tokens para todas as imagens e texto não deve exceder o limite máximo de entrada do modelo.
Outros recursos
Modelo | |||||||
|---|---|---|---|---|---|---|---|
kimi-k3.1-pro | Suportado | Suportado | Suportado | Suportado (JSON Mode) | Suportado | Não suportado | Suportado (cache implícito) |
kimi-k3 | Suportado | Suportado | Suportado | Suportado | Suportado (Responses API) | Suportado | Suportado |
kimi-k2.7-code | Suportado | Suportado | Suportado | Não suportado | Não suportado | Não suportado | Suportado |
kimi-k2.6 | Suportado | Suportado | Suportado | Não suportado | Não suportado | Não suportado | Suportado |
kimi-k2.5 | Suportado | Suportado | Suportado | Não suportado | Não suportado | Não suportado | Suportado |
Ferramentas carregadas dinamicamente
Quando uma aplicação precisa disponibilizar muitas ferramentas, incluir todas as declarações de ferramenta de uma só vez no campo tools de nível superior da requisição causa um excesso de definições de ferramentas: cada requisição precisa transportar a descrição e o esquema de parâmetros de todas as ferramentas, aumentando o consumo de tokens; além disso, quanto mais ferramentas candidatas houver, maior será a probabilidade de o modelo selecionar a ferramenta errada e construir argumentos de chamada incorretos.
As ferramentas carregadas dinamicamente permitem injetar ferramentas sob demanda durante uma conversa: primeiro, disponibilize apenas algumas ferramentas principais e, quando a conversa chegar a um ponto que exija uma ferramenta específica, insira-a dinamicamente em messages. Isso reduz o consumo de tokens e aumenta a precisão da seleção de ferramentas.
tokenization failed.O formato e os exemplos desta seção para injetar ferramentas em messages por meio do campo tools de uma mensagem system (system.tools) se aplicam à API OpenAI Chat Completions.Injetar declarações de ferramentas em mensagens
Insira em messages uma mensagem cujo role seja system e declare no campo tools dessa mensagem as ferramentas que devem ser carregadas. O formato é idêntico ao do campo tools de nível superior da requisição, e você deve fornecer as informações completas da ferramenta (name, description, parameters).
- Uma mensagem
systemcomtoolstem o mesmo status de uma mensagem comum: as ferramentas ficam visíveis para o modelo a partir da posição em que a mensagem aparece na listamessages. - As ferramentas carregadas dinamicamente coexistem com as ferramentas globais declaradas no campo
toolsde nível superior da requisição; o modelo pode ver os dois tipos simultaneamente. - Uma declaração de ferramenta injetada dinamicamente deve ser uma definição completa; não é possível passar apenas o nome da ferramenta nem fazer referência a uma ferramenta declarada globalmente.
- Uma mensagem
systemcomtoolsnão pode conter também o campocontent; caso contrário, a requisição falha com um erro 400. Ao usar o OpenAI SDK, você pode passar o campotoolsdiretamente emmessages.
Carregamento sob demanda combinado com uma ferramenta de pesquisa
Não há uma API dedicada à pesquisa de ferramentas. Quando houver muitas ferramentas, você poderá combinar uma ferramenta de pesquisa personalizada com ferramentas carregadas dinamicamente para carregá-las sob demanda:
- No início da sessão, declare no campo
toolsde nível superior apenas uma ferramentasearch_toolsimplementada pelo backend da aplicação (ela retorna nomes e resumos das ferramentas correspondentes a uma palavra-chave), além de algumas ferramentas principais que podem ser usadas em cada turno. - Declare no prompt do sistema as palavras-chave pesquisáveis, como um catálogo de ferramentas ou tags de domínio, para orientar o modelo a chamar
search_toolsprimeiro quando precisar de uma ferramenta. Definirtool_choice: "required"na primeira requisição garante pelo menos uma chamada de ferramenta, mas não garante quesearch_toolsseja chamada primeiro. Se a pesquisa inicial for obrigatória, defina explicitamentetool_choice: {"type": "function", "function": {"name": "search_tools"}}e, depois da pesquisa, restauretool_choicepara"auto". Alterartool_choicenão invalida o cache de prefixo. - Com base nos resultados retornados por
search_tools, a aplicação insere dinamicamente emmessagesas declarações completas das ferramentas correspondentes por meio de uma mensagemsystemcomtools. - Em seguida, o modelo pode chamar diretamente essas ferramentas recém-carregadas nas gerações posteriores.
Observações
- As declarações dinâmicas de ferramentas entram em vigor por requisição e não são memorizadas pelo servidor. Cabe ao integrador decidir se continuará a enviá-las na próxima requisição: se continuar, as ferramentas permanecerão disponíveis, o que também ajuda a obter acertos no cache de prefixo; se parar, a declaração expirará. Se a ferramenta não estiver declarada em outro local, o modelo não poderá chamá-la, e o cache de prefixo após o ponto da alteração poderá não ser utilizado.
- Acrescentar uma declaração dinâmica de ferramenta ao final de
messagesnão afeta o cache do prefixo existente; excluir ou modificar declarações anteriores pode afetar os acertos no cache após o ponto da alteração. Declarar ferramentas globais no campotoolsde nível superior da requisição também não afeta os acertos no cache. - Uma mensagem
systemcomtoolstambém consome comprimento de contexto; portanto, injete apenas as ferramentas realmente necessárias para a conversa atual. - As declarações dinâmicas de ferramentas usam exatamente o mesmo formato das declarações globais de
tools; portanto, os integradores não precisam manter dois esquemas.
Parâmetros padrão
Modelo | enable_thinking | temperature | top_p | presence_penalty | fps | max_frames |
|---|---|---|---|---|---|---|
kimi-k3.1-pro | true (pode ser desativado; é altamente recomendável mantê-lo ativado) | 1.0 | 0.95 | 0.0 | - | - |
kimi-k3 | true (pode ser desativado; é recomendável mantê-lo ativado) | 1.0 | 0.95 | 0.0 | - | - |
kimi-k2.7-code | true (apenas modo de raciocínio) | 1.0 | 0.95 | 0.0 | 2 | 2000 |
kimi-k2.6 | false | modo de raciocínio: 1.0 modo sem raciocínio: 0.6 | Ambos os modos: 0.95 | Ambos os modos: 0.0 | 2 | 2000 |
kimi-k2.5 | false | modo de raciocínio: 1.0 modo sem raciocínio: 0.6 | Ambos os modos: 0.95 | Ambos os modos: 0.0 | 2 | 2000 |
temperature=1.0, top_p=0.95 e presence_penalty=0.0. Passar um valor diferente do padrão para qualquer um desses parâmetros retorna um erro.
Os níveis de esforço de raciocínio a seguir se aplicam apenas a kimi-k3.1-pro, com max como padrão:
max(padrão): raciocínio profundohigh: raciocínio aprimoradomedium: raciocínio moderadolow: raciocínio leve
- OpenAI Chat Completions: use o campo de nível superior
reasoning_effort. Com o OpenAI Python SDK, passereasoning_effort="max"diretamente. - DashScope: use o parâmetro
reasoning_effortdo SDK ouparameters.reasoning_effortem requisições HTTP. - OpenAI Responses: use
reasoning.effort. - Anthropic Messages: use
output_config.effort.
Modelos e faturamento
A série Kimi consiste em grandes modelos de linguagem da Moonshot AI.
- kimi-k3.1-pro: Suporta entrada de texto e imagem, saída de texto e carregamento dinâmico de ferramentas. Entrada de vídeo, Batch e ajuste fino não são suportados.
- kimi-k3: modelo principal da Kimi. Usa raciocínio e preserva o raciocínio por padrão. Suporta entrada de texto e imagem (não suporta entrada de vídeo), conversação, tarefas de agente e carregamento dinâmico de ferramentas.
- kimi-k2.7-code: um modelo Kimi para codificação. Segue instruções de contexto longo com mais confiabilidade e alcança taxas de sucesso mais altas em tarefas de programação. Suporta entrada de texto, imagem e vídeo, modo de raciocínio, conversação e tarefas de agente.
- kimi-k2.6: um modelo da série Kimi com desempenho aprimorado em codificação de longo horizonte, seguimento de instruções e autocorreção. Suporta entrada de texto, imagem e vídeo, modos de raciocínio e sem raciocínio, conversação e tarefas de agente.
- kimi-k2.5: Alcança desempenho de última geração (SOTA) em benchmarks de código aberto para tarefas de agente, geração de código, compreensão visual e outras tarefas de inteligência geral. Suporta entrada de imagem, vídeo e texto, modos de raciocínio e sem raciocínio, conversação e tarefas de agente.
thinking_budget. Você não pode usar esse parâmetro para limitar a duração do pensamento.Para consultar os preços, veja faturamento de chamadas de modelo.Para detalhes sobre preços e janela de contexto, consulte o console do Model Studio. O faturamento é baseado nas contagens de tokens de entrada e saída.
No modo de raciocínio, a cadeia de pensamento conta como tokens de saída.