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 compila para todas as plataformas: Win32, Win64, macOS, Linux64, iOS e Android, e a IDE o oferece nos formulários de todas elas. As chamadas HTTPS exigem a configuração TLS habitual de cada plataforma, por exemplo as bibliotecas OpenSSL no Linux. Veja a tabela abaixo.

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 796, dentro do bloco `{$IFDEF SGC_EDT_ENT}` que vai da linha 759 à linha 842. 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 857, e seu próprio bloco nas linhas 946 a 959 define `SGC_AI` na linha 947. Os mesmos componentes, sem o restante da biblioteca.
Plataformas	Nenhuma das duas definições de `SGC_AI`, linha 796 e linha 947, tem restrição de plataforma, então `sgcAI_Chat.pas` compila para todos os destinos e o componente carrega `ComponentPlatforms(0)`. Somente `TsgcAudioRecorderMCI`, `TsgcAudioRecorderWave`, `TsgcAudioPlayerMCI` e `TsgcTextToSpeechSystem`, que chamam APIs de áudio e fala do Windows, são compilados apenas no Windows.
O que é multiplataforma	`SGC_AI_MCP`, na linha 797 e na linha 955, 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 786 a 792, também não são restritos por plataforma.

Está construindo um serviço Linux ou um aplicativo móvel? O TsgcAIChat também compila nesses destinos. Como alternativa, 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 a paleta da IDE oferece esses componentes apenas em Win32 e Win64, embora as units compilem em todas as plataformas.

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.

Compilando para Linux, macOS ou mobile

sgcAI_Chat.pas compila para todas as plataformas. TsgcAudioRecorderMCI, TsgcAudioRecorderWave, TsgcAudioPlayerMCI e TsgcTextToSpeechSystem chamam APIs de áudio e fala do Windows e são compilados somente no Windows, então mantenha-os fora de um formulário multiplataforma. As chamadas HTTPS exigem a configuração TLS habitual de cada plataforma, por exemplo as bibliotecas OpenSSL no Linux.

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 796 de sgcVer.inc, dentro do bloco SGC_EDT_ENT que vai da linha 759 à linha 842. Isso é a edição Enterprise e superiores. A Standard, linhas 674 a 723, e a Professional, linhas 726 a 757, não o definem. Se você não quer o restante da biblioteca, o pacote sgcAI independente define SGC_PACK_AI na linha 857, cujo próprio bloco nas linhas 946 a 959 ativa os mesmos componentes.

Sim. SGC_AI é definido sem restrição de plataforma, na linha 796 do bloco Enterprise e na linha 947 do bloco do pacote independente, então sgcAI_Chat.pas e sgcAI.pas compilam para Windows, macOS, Linux, iOS e Android, e o TsgcAIChat carrega ComponentPlatforms(0). As exceções são TsgcAudioRecorderMCI, TsgcAudioRecorderWave, TsgcAudioPlayerMCI e TsgcTextToSpeechSystem, que chamam APIs de áudio e fala do Windows e são compilados somente no Windows. As chamadas HTTPS exigem a configuração TLS habitual de cada plataforma, por exemplo as bibliotecas OpenSSL no Linux.

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