Posso manter a interface responsiva durante uma geração longa?

No Delphi 2010 e posteriores, chame ChatAsync, que está envolvido em {$IFDEF D2010} e retorna um IsgcFuture . Do Delphi 7 ao 2009 esse método não existe, então execute Chat em uma thread que você mesmo criar.

Início rápido do sgcAI

Visão geral

O que a primeira chamada precisa

Um componente, uma chave, o nome de um modelo e um prompt. Sem JSON para montar e sem cliente HTTP para configurar.

Componente

TsgcAIChat na página SGC AI da paleta. É um wrapper publicado fino em torno de TsgcAI_Chat, que é o que os demos que acompanham o pacote criam em código.

Unit

sgcAI_Chat.pas para a classe, ou a unit barrel sgcAI.pas para o componente da paleta. Os demos escrevem uses sgcAI_Chat;.

A única propriedade que troca de fornecedor

Provider, do tipo TsgcAIChatProvider. Os sete membros são aicpOpenAI, aicpAnthropic, aicpGemini, aicpDeepSeek, aicpOllama, aicpGrok e aicpMistral. Nada mais no seu código muda.

Plataforma, leia esta

TsgcAIChat é compilado somente para Windows, Win32 e Win64. Os clientes REST por fornecedor e o cliente e servidor MCP não têm restrição. Veja a tabela abaixo para entender o motivo.

Antes de começar

Requisitos e edições

A coluna de edição é o define que controla o código, com a linha em que ele aparece em Source/sgcVer.inc.

O quê	Valor
IDE	Do Delphi 7 ao RAD Studio 13, e as versões correspondentes do C++Builder. `ChatAsync` é o único membro com um piso mais alto, porque está envolvido em `{$IFDEF D2010}`.
Cláusula uses	`sgcAI_Chat` para `TsgcAI_Chat`, `TsgcAIChatProvider` e os tipos de evento.
Edição, dentro do sgcWebSockets	`SGC_AI` é definido na linha 798, dentro do bloco `{$IFDEF SGC_EDT_ENT}` que vai da linha 760 à linha 839. Ou seja, Enterprise e superiores, não Standard e não Professional.
Edição, pacote independente	O produto sgcAI define `SGC_PACK_AI` na linha 854, e seu próprio bloco nas linhas 943 a 957 define `SGC_AI` na linha 945. Os mesmos componentes, sem o restante da biblioteca.
Por que somente Windows	As duas definições de `SGC_AI` ficam dentro de um `{$IFDEF MSWINDOWS}`, na linha 797 e na linha 944. Fora do Windows, o define nunca aparece, então `sgcAI_Chat.pas` compila como uma unit vazia. O componente também carrega `ComponentPlatforms(pidWin32 or pidWin64)`.
O que é multiplataforma	`SGC_AI_MCP`, na linha 800 e na linha 954, não tem restrição de plataforma. Portanto, o cliente e o servidor MCP também rodam em Linux, macOS, iOS e Android. Os defines de provedores `SGC_OPENAI`, `SGC_ANTHROPIC`, `SGC_GEMINI`, `SGC_DEEPSEEK`, `SGC_OLLAMA`, `SGC_GROK` e `SGC_MISTRAL`, linhas 787 a 793, também não são restritos por plataforma.

Está construindo um serviço Linux ou um aplicativo móvel? Pule TsgcAIChat e chame diretamente o cliente REST do fornecedor, por exemplo TsgcHTTP_API_OpenAI ou TsgcHTTP_API_Anthropic. O guia chamar um LLM a partir do Delphi mostra as duas rotas lado a lado.

Passo 1

Instale e encontre a página da paleta

O sgcAI acompanha o instalador do sgcWebSockets e também como pacote próprio. De qualquer forma, a instalação tem o mesmo formato.

1. Descompacte

Descompacte o download em uma pasta, chamada de {$DIR} abaixo.

2. Caminho da biblioteca

Tools, Options, Library. Adicione {$DIR}\source e a pasta lib da sua IDE, por exemplo {$DIR}\libD13\$(Platform).

3. Compile os pacotes

Abra o grupo de pacotes da versão da sua IDE em {$DIR}\Packages\. Compile primeiro o .dpk de runtime e depois instale o de design-time, o dcl.

4. Confira a paleta

Aparece uma página chamada SGC AI com quinze componentes. TsgcAIChat é o primeiro. Se a página não aparecer em um destino que não seja Windows, é o esperado, porque SGC_AI é restrito ao Windows.

5. Obtenha uma chave de API

Para um provedor hospedado, você usa sua própria chave desse fornecedor e a atribui a ChatOptions.ApiKey. O Ollama não precisa de chave alguma, porque o modelo roda na sua máquina.

QuickStart

Sua primeira resposta, em cerca de dez linhas

Crie o componente, defina um provedor, uma chave e um modelo, depois chame Chat e leia a string que ele retorna.

fUnifiedChat.pas

uses
  Classes, SysUtils,
  // sgc
  sgcAI_Chat;

procedure TfrmUnifiedChat.btnChatClick(Sender: TObject);
var
  oChat: TsgcAI_Chat;
begin
  oChat := TsgcAI_Chat.Create(nil);
  try
    oChat.Provider := aicpOpenAI;
    oChat.ChatOptions.ApiKey := GetApiKey;
    oChat.ChatOptions.Model := 'gpt-4o-mini';
    oChat.ChatOptions.MaxTokens := 1024;
    oChat.SystemMessage := 'You are a concise assistant inside a Delphi ERP.';

    memoResponse.Lines.Text := oChat.Chat(memoPrompt.Text);
  finally
    oChat.Free;
  end;
end;

Trocar de fornecedor é uma linha. Provider aceita aicpOpenAI, aicpAnthropic, aicpGemini, aicpDeepSeek, aicpOllama, aicpGrok e aicpMistral. Todo o resto continua onde está.

fUnifiedChat.pas

procedure TfrmUnifiedChat.OnChatStream(Sender: TObject; const aChunk: string;
  var Cancel: Boolean);
begin
  memoResponse.Text := memoResponse.Text + aChunk;
  // set Cancel to stop the generation early
end;

procedure TfrmUnifiedChat.OnChatError(Sender: TObject; const aError: string);
begin
  memoResponse.Text := 'error: ' + aError;
end;

procedure TfrmUnifiedChat.btnChatStreamClick(Sender: TObject);
begin
  GetChat.Provider := aicpAnthropic;
  GetChat.ChatOptions.ApiKey := GetApiKey;
  GetChat.ChatOptions.Model := 'claude-sonnet-4-20250514';
  GetChat.SystemMessage := memoSystem.Text;

  memoResponse.Lines.Clear;
  GetChat.ChatStream(memoPrompt.Text);
end;

O demo monta seu componente uma vez em GetChat e atribui OnChatStream e OnChatError ali. ChatStream também retorna a resposta completa, então você pode ignorar o valor de retorno e usar apenas o evento, ou usar os dois.

uLocal.pas

uses
  Classes, SysUtils,
  // sgc
  sgcAI_Chat;

var
  oChat: TsgcAI_Chat;
begin
  oChat := TsgcAI_Chat.Create(nil);
  try
    // no API key at all: the model runs on this machine
    oChat.Provider := aicpOllama;
    oChat.ChatOptions.Model := 'llama3';

    // BaseUrl is read only for the Ollama provider, and only when
    // the server is not on the default address. Internally it is
    // forwarded to the Ollama client's Host property.
    oChat.ChatOptions.BaseUrl := 'http://localhost:11434';

    Writeln(oChat.Chat('Summarise this invoice in one line.'));
  finally
    oChat.Free;
  end;
end;

Não existe OllamaOptions.BaseUrl. No nível da API pura, a propriedade é OllamaOptions.Host em TsgcHTTP_API_Ollama, e ChatOptions.BaseUrl é o que a alimenta a partir desta camada.

As duas primeiras abas são o demo que acompanha o pacote, Demos\15.AI\02.Applications\06.UnifiedChat\fUnifiedChat.pas, com os controles do formulário substituídos por literais. A terceira aba é o mesmo componente apontado para um servidor Ollama local. Um segundo demo, 07.ConversationHistory, mostra a API de histórico na mesma pasta.

Passo 2

Confira se funcionou e veja a falha quando não funcionar

Chat não gera exceção em uma chamada que falha, o que surpreende as pessoas. Ele retorna uma string vazia e dispara um evento.

O valor de retorno

Chat retorna o texto do assistente como uma string. Uma string vazia significa que a chamada falhou, porque uma falha não gera exceção.

`OnChatError`

procedure(Sender: TObject; const aError: string). Tanto Chat quanto ChatStream capturam a exceção e a encaminham para cá. Este é o primeiro evento a conectar, antes de qualquer outro.

`OnChatStream`

procedure(Sender: TObject; const aChunk: string; var Cancel: Boolean). Texto aparecendo no memo enquanto o modelo ainda está escrevendo é a prova de que o streaming está funcionando, e não apenas armazenando em buffer.

A conversa

GetHistory retorna o que o componente vai reenviar na próxima chamada. MaxHistoryMessages limita o tamanho e ClearHistory recomeça do zero.

Problemas comuns

O que costuma dar errado na primeira vez

Seis problemas respondem por quase toda primeira chamada que falha.

A unit não compila fora do Windows

É por projeto. SGC_AI é definido dentro de um {$IFDEF MSWINDOWS} na linha 797 e novamente na linha 944, então em Linux, macOS, iOS e Android sgcAI_Chat.pas é uma unit vazia. Use os clientes REST dos fornecedores nesses destinos.

Chat retorna uma string vazia e nada é gerado como exceção

Chat e ChatStream engolem a exceção e a encaminham para OnChatError, cuja assinatura é procedure(Sender: TObject; const aError: string). Conecte esse evento antes de depurar qualquer outra coisa.

Um modelo Ollama local é ignorado

O endereço base do Ollama vai em ChatOptions.BaseUrl, não no objeto de opções do fornecedor. Ele é encaminhado internamente para OllamaOptions.Host, e é o único provedor para o qual BaseUrl é lido.

O formulário congela durante uma resposta longa

Chat e ChatStream são síncronos. No Delphi 2010 e posteriores, use ChatAsync, que retorna um IsgcFuture<string>. Em compiladores mais antigos, execute a chamada em uma thread sua.

O nome do modelo é rejeitado

Os nomes de modelo pertencem ao fornecedor, não ao componente, e mudam. ChatOptions.Model é repassado direto, então um nome que funciona no console do fornecedor funciona aqui.

A conta cresce em uma conversa longa

O componente reenvia o histórico a cada chamada, e é isso que faz uma pergunta de acompanhamento funcionar. Limite-o com MaxHistoryMessages e recomece com ClearHistory.

Aprofunde-se

O que as pessoas constroem depois da primeira resposta

Uma caixa de prompt é o começo. Os quatro itens abaixo já estão no pacote.

Responda a partir dos seus próprios documentos

Transforme seu conteúdo em vetores com TsgcAIOpenAIEmbeddings, armazene-os em TsgcAIDatabaseVectorFile ou TsgcAIDatabaseVectorPinecone e recupere os trechos mais próximos para colocar no prompt.

Referência de embeddings e referência de bancos de dados vetoriais

Converse com ele em voz alta

TsgcAIOpenAIChatBot reúne um gravador, a transcrição, a chamada de chat e a conversão de texto em fala em um único componente. TsgcAIOpenAITranslator faz o mesmo para tradução ao vivo.

Referência do ChatBot e referência do tradutor

Exponha seu aplicativo a um agente

O componente servidor MCP transforma seu aplicativo em uma ferramenta que um assistente pode chamar, e o cliente MCP consome outros servidores. Nenhum dos dois é restrito ao Windows, então um servidor MCP escrito em Delphi roda no Linux.

Referência do servidor MCP e referência do cliente MCP

Use a API completa do fornecedor

Visão, documentos, raciocínio estendido, lotes, geração de imagens, transcrição e moderação ficam nos clientes REST de cada fornecedor, e não na camada de chat neutra.

Referência da OpenAI e referência da Anthropic

Recursos

Referência, demos e documentação

As páginas de referência documentam cada opção e evento. Os projetos de demo acompanham o download, em Demos\15.AI.

	Guia, chamar um LLM a partir do Delphi O passo a passo completo: streaming, chamada de ferramentas e hospedado contra local.	Abrir
	Referência, cliente OpenAI Cada método, opção e evento de `TsgcHTTP_API_OpenAI`.	Abrir
	Referência, cliente Anthropic Mensagens, ferramentas, visão, lotes e contagem de tokens em `TsgcHTTP_API_Anthropic`.	Abrir
	Referência, servidor MCP O componente que permite a um assistente chamar seu aplicativo.	Abrir
	Página do componente TsgcAIChat Cada propriedade e evento do componente de chat, com os outros quatorze ligados a partir dela.	Abrir
	Ajuda online A referência gerada, sempre alinhada com a versão atual.	Abrir

Leitura relacionada: criando aplicativos Delphi com IA, comparando os provedores a partir do Delphi e escrevendo um servidor MCP. Cada produto tem seu próprio início rápido, listado na página de primeiros passos.

FAQ

Perguntas sobre o início rápido do sgcAI

Solte TsgcAIChat da página SGC AI da paleta. Ele é declarado em sgcAI.pas como um wrapper publicado em torno de TsgcAI_Chat, que é declarado em sgcAI_Chat.pas. O código que cria o objeto em tempo de execução, como fazem os demos que acompanham o pacote, usa TsgcAI_Chat e uses sgcAI_Chat;. Os dois oferecem as mesmas propriedades.

Dentro do sgcWebSockets, o controle é SGC_AI, definido na linha 798 de sgcVer.inc, dentro do bloco SGC_EDT_ENT que vai da linha 760 à linha 839. Isso é a edição Enterprise e superiores. A Standard, linhas 675 a 724, e a Professional, linhas 727 a 758, não o definem. Se você não quer o restante da biblioteca, o pacote sgcAI independente define SGC_PACK_AI na linha 854, cujo próprio bloco nas linhas 943 a 957 ativa os mesmos componentes.

Porque SGC_AI só é definido dentro de um {$IFDEF MSWINDOWS}, na linha 797 do bloco Enterprise e na linha 944 do bloco do pacote independente. Com o define ausente, sgcAI_Chat.pas e a seção TsgcAIChat de sgcAI.pas compilam para nada. O design-time espelha isso com ComponentPlatforms(pidWin32 or pidWin64). Nesses destinos, chame os clientes REST dos fornecedores ou use os componentes MCP, que não têm restrição de plataforma.

Mude Provider. Ele aceita aicpOpenAI, aicpAnthropic, aicpGemini, aicpDeepSeek, aicpOllama, aicpGrok e aicpMistral. Depois defina a chave e o modelo desse fornecedor. Para aicpOllama não há chave, e se o servidor não estiver no endereço padrão, você define ChatOptions.BaseUrl, que o componente encaminha internamente para o cliente Ollama.

Chame ChatStream em vez de Chat e trate OnChatStream. Sua assinatura é procedure(Sender: TObject; const aChunk: string; var Cancel: Boolean): acrescente aChunk ao seu memo conforme ele chega e defina Cancel como True para interromper a geração antes do fim.

Chat e ChatStream não geram exceção. Eles capturam a exceção, disparam OnChatError com a mensagem e retornam uma string vazia. Portanto, um OnChatError sem tratamento parece exatamente um modelo que respondeu com nada. Conecte-o primeiro.

No Delphi 2010 e posteriores, chame ChatAsync, que está envolvido em {$IFDEF D2010} e retorna um IsgcFuture<string>. Do Delphi 7 ao 2009 esse método não existe, então execute Chat em uma thread que você mesmo criar.

Sim. Ele guarda a troca de mensagens e a reenvia na próxima chamada, e é isso que faz uma pergunta de acompanhamento funcionar. MaxHistoryMessages limita quanto é reenviado, ClearHistory inicia uma nova conversa e GetHistory retorna as mensagens armazenadas.

sgcAI em cinco minutos