Streaming

Por padrão, uma completion retorna quando a resposta inteira está pronta. Com stream: true, a API começa a responder assim que o modelo produz os primeiros tokens, então você pode mostrar progresso a um usuário ou começar a processar mais cedo. Streaming está disponível com canvas_id e version_id. Tarefas criadas com application_id sempre rodam de forma assíncrona e não usam streaming.

Habilitando o stream

Acrescente stream: true à requisição. Com os SDKs, a completion retornada passa a ser um iterável de chunks.

import fs from 'node:fs'
import { createTelaClient } from '@meistrari/tela-sdk-js'
import type { TelaFile } from '@meistrari/tela-sdk-js'

const tela = createTelaClient({
    apiKey: process.env.TELA_API_KEY,
})

const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
    stream: true,
})

for await (const chunk of completion) {
    console.log(JSON.stringify(chunk))
}

import fs from 'node:fs'
import { createTelaClient } from '@meistrari/tela-sdk-js'

const tela = createTelaClient({
    apiKey: process.env.TELA_API_KEY,
})

const completion = await tela.completions.create({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
    stream: true,
})

for await (const chunk of completion) {
    console.log(JSON.stringify(chunk))
}

import os
from tela import create_tela_client

client = create_tela_client(
    api_key=os.getenv("TELA_API_KEY"),
)

with open("./sample-invoice.pdf", "rb") as file:
    completion = client.completions.create(
        canvas_id=os.getenv("TELA_CANVAS_ID"),
        variables={
            "document": client.create_file(file),
        },
        stream=True,
    )

    for chunk in completion:
        print(chunk)

curl -X POST https://api.tela.com/v2/chat/completions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -d '{
        "canvas_id": "95cec438-6080-44fe-8275-28b16bd40178",
        "variables": {
            "document": { "file_url": "data:application/pdf;base64,JVBERi0xLjUKJeLjz9MKNCAwIG9ia..." }
        },
        "stream": true
    }'

O que cada chunk contém

Cada chunk é um objeto de stream de chat.completion. Os campos que você vai usar:

Campo	Significado
`id`, `object`, `created`, `model`	Identificam a completion e o modelo que está respondendo.
`choices[].delta.content`	O trecho de texto produzido desde o chunk anterior. Concatene os deltas para reconstruir a resposta.
`choices[].delta.role`	O papel da mensagem (`assistant`) quando presente, caso contrário `null`.
`choices[].finish_reason`	`null` enquanto o modelo ainda está gerando; um valor quando ele para.
`choices[].index`	A posição da escolha.
`message`	O objeto de mensagem da resposta de stream: `role`, `content` e `structured_content` quando o Canvas tem um Formato de Saída.

Use delta.content para exibir o texto conforme ele chega, e leia message.structured_content quando precisar dos campos do Formato de Saída em vez do texto. O schema completo está em Run Canvas.

O formato do stream por HTTP puro (como os chunks são delimitados no corpo da resposta) não está documentado aqui. Os SDKs cuidam disso para você; se você consumir o stream com o seu próprio cliente HTTP, inspecione a resposta bruta antes.

Quando não usar streaming

O streaming mantém a conexão HTTP aberta durante toda a execução. Para documentos longos processados em segundo plano, ou quando quem chama não precisa da saída parcial, prefira async ou uma webhook_url e leia o resultado quando ele estiver pronto.

Primeiros passos

Construir

Testar

Operar

Integrar

Habilitando o stream

O que cada chunk contém

Quando não usar streaming

​Habilitando o stream

​O que cada chunk contém

​Quando não usar streaming

Habilitando o stream

O que cada chunk contém

Quando não usar streaming