Gemini API Delphi 클라이언트

· 컴포넌트

Google Gemini는 현재 가장 강력한 멀티모달 AI 모델 패밀리 중 하나로, 텍스트 생성, 이미지 이해, 구조화된 출력, 함수 호출 등 다양한 사용 사례에서 탁월한 성능을 발휘해요. Gemini를 애플리케이션에 통합하려는 Delphi 개발자를 위해 sgcWebSockets는 Google Gemini API 전체를 래핑하는 포괄적인 네이티브 컴포넌트 TsgcHTTP_API_Gemini를 제공해요.

대화형 어시스턴트 구축, 구조화된 데이터 생성, 이미지 처리, 시맨틱 검색용 임베딩 생성, 도구 기반 워크플로 오케스트레이션 등 무엇을 만들든 이 컴포넌트는 깔끔하고 타입 안전한 Delphi 코드로 모든 Gemini 기능에 직접 접근할 수 있게 해줘요. REST 보일러플레이트도, JSON 처리도 필요 없어요. 컴포넌트를 추가하고 API 키를 설정하기만 하면 바로 개발을 시작할 수 있어요.

완전한 API 지원

Google Gemini API의 모든 주요 기능을 기본으로 지원해요.

콘텐츠 생성
선택적 시스템 지시와 함께 프롬프트에서 텍스트를 생성해요. 온도, top-p, top-k, 정지 시퀀스로 출력을 세밀하게 조정할 수 있어요. 		실시간 스트리밍
Server-Sent Events를 사용해 토큰 단위로 응답을 스트리밍해요. 답변이 생성되는 동시에 표시하는 반응형 UI를 만들 수 있어요. 		비전
텍스트 프롬프트와 함께 base64 인코딩된 이미지를 전송해 이미지를 분석해요. Gemini가 시각적 콘텐츠를 설명하고 해석하고 추론해요.
구조화된 JSON 출력
Gemini가 스키마에 맞는 유효한 JSON을 반환하도록 강제해요. 응답 MIME 타입과 스키마를 설정하면 파싱 가능한 결과를 보장해요. 		함수 호출
JSON Schema로 사용자 정의 함수를 정의해요. Gemini가 함수를 언제 호출할지 결정해 에이전트 기반 멀티스텝 워크플로를 구현해요. 		임베딩
텍스트의 벡터 임베딩을 생성해요. 시맨틱 검색, 클러스터링, 분류, 추천 시스템을 구현할 수 있어요.
토큰 계산
요청을 전송하기 전에 토큰 수를 세요. 비용을 정확히 추정하고 컨텍스트 창 예산을 관리할 수 있어요. 		모델 관리
사용 가능한 모든 Gemini 모델을 나열하거나 입출력 토큰 한도를 포함한 특정 모델의 세부 정보를 조회해요. 		내장 재시도 및 로깅
설정 가능한 재시도 횟수와 대기 간격으로 일시적 오류 시 자동 재시도해요. 디버깅을 위한 전체 요청/응답 로깅을 지원해요.

시작하기

Google Gemini를 Delphi 프로젝트에 1분 이내에 통합할 수 있어요. 컴포넌트를 추가하고 API 키를 설정한 뒤 첫 번째 메시지를 전송해 보세요.

// Create the component and configure the API key
var
  Gemini: TsgcHTTP_API_Gemini;
  vResponse: string;
begin
  Gemini := TsgcHTTP_API_Gemini.Create(nil);
  Try
    Gemini.GeminiOptions.ApiKey := 'YOUR_API_KEY';
    // Send a simple message to Gemini
    vResponse := Gemini._CreateContent(
      'gemini-2.5-flash', 'Hello, Gemini!');
    ShowMessage(vResponse);
  Finally
    Gemini.Free;
  End;
end;

두 가지 API 스타일. 모든 기능은 편의 메서드(문자열 기반, 최소한의 코드)와 타입 지정 요청/응답 클래스(완전한 제어, 타입 안전성) 모두를 제공해요. 사용 사례에 가장 적합한 방식을 선택하세요.

콘텐츠 생성 및 스트리밍

GenerateContent API는 모든 Gemini 상호작용의 기반이에요. 선택적 시스템 지시와 함께 텍스트를 전송하면 동기 또는 실시간 스트리밍 방식으로 응답을 받을 수 있어요.

시스템 지시

대화의 컨텍스트, 성격, 제약 조건을 설정하는 시스템 지시를 제공해 Gemini의 동작을 제어하세요.

vResponse := Gemini._CreateContentWithSystem(
  'gemini-2.5-flash',
  'You are a helpful assistant that responds in Spanish.',
  'What is the capital of France?');
// Returns: "La capital de Francia es París."

실시간 스트리밍

반응형 사용자 인터페이스를 위해 Server-Sent Events를 사용해 Gemini의 응답을 토큰 단위로 스트리밍해요. OnHTTPAPISSE 이벤트 핸들러를 할당하고 _CreateContentStream을 호출하세요.

// Enable streaming via SSE
Gemini.OnHTTPAPISSE := OnSSEEvent;
Gemini._CreateContentStream('gemini-2.5-flash',
  'Tell me a story about a brave explorer.');
procedure TForm1.OnSSEEvent(Sender: TObject;
  const aEvent, aData: string; var Cancel: Boolean);
begin
  // aData: JSON payload with generated content
  Memo1.Lines.Add(aData);
end;

고급 타입 지정 API

온도, top-p, top-k, 정지 시퀀스, 최대 출력 토큰 등 요청 파라미터를 완전히 제어하려면 타입 지정 요청 및 응답 클래스를 사용하세요.

var
  oRequest: TsgcGeminiClass_Request_GenerateContent;
  oResponse: TsgcGeminiClass_Response_GenerateContent;
begin
  oRequest := TsgcGeminiClass_Request_GenerateContent.Create;
  Try
    oRequest.Model := 'gemini-2.5-flash';
    oRequest.SystemInstruction := 'You are a helpful assistant.';
    oRequest.MaxOutputTokens := 2048;
    oRequest.Temperature := 0.7;
    oRequest.TopP := 0.9;
    oRequest.TopK := 40;
    oRequest.Contents.Add('user', 'Explain quantum computing in simple terms.');
    oResponse := Gemini.CreateContent(oRequest);
    Try
      if Length(oResponse.Candidates) > 0 then
        ShowMessage(oResponse.Candidates[0].Parts[0].Text);
    Finally
      oResponse.Free;
    End;
  Finally
    oRequest.Free;
  End;
end;

비전 — 이미지 이해

Gemini는 기본적으로 멀티모달이에요. 텍스트 프롬프트와 함께 사진, 스크린샷, 다이어그램, 차트를 전송하면 상세한 설명, 데이터 추출, 시각적 Q&A를 받을 수 있어요.

// Load an image and ask Gemini to describe it
var
  vBase64: string;
begin
  vBase64 := sgcBase64Encode(LoadFileToBytes('product-photo.png'));
  ShowMessage(Gemini._CreateVisionContent(
    'gemini-2.5-flash',
    'Describe this product image for an e-commerce listing.',
    vBase64, 'image/png'));
end;

사용 사례. 품질 검사 자동화, 접근성을 위한 대체 텍스트 생성, 차트에서 데이터 추출, 시각적 검색 기능 구축 등 모든 것을 네이티브 Delphi 코드로 구현할 수 있어요.

구조화된 JSON 출력

Gemini가 정확한 스키마에 맞는 유효하고 파싱 가능한 JSON을 반환하도록 보장해요. 응답 MIME 타입과 스키마를 설정하면 후처리가 필요 없고 응답을 Delphi 레코드로 바로 역직렬화할 수 있어요.

var
  vSchema, vResponse: string;
begin
  vSchema :=
    '{"type":"object","properties":{"name":{"type":"string"},' +
    '"age":{"type":"integer"}},"required":["name","age"]}';
  vResponse := Gemini._CreateContentJSON(
    'gemini-2.5-flash',
    'Extract the name and age: John is 30 years old.',
    vSchema);
  // Returns: {"name": "John", "age": 30}
end;

스키마 강제 적용. ResponseMimeType을 'application/json'으로 설정하고 ResponseSchema를 제공하면 Gemini가 매번 구조적으로 유효한 출력을 보장해요.

함수 호출

JSON Schema로 사용자 정의 함수를 정의하면 Gemini가 언제, 어떻게 호출할지 결정해요. 이는 AI를 비즈니스 로직에 연결하는 에이전트 기반 멀티스텝 워크플로를 구축하는 기반이에요.

var
  oRequest: TsgcGeminiClass_Request_GenerateContent;
  oFunc: TsgcGeminiClass_Request_FunctionDeclaration;
  oResponse: TsgcGeminiClass_Response_GenerateContent;
begin
  oRequest := TsgcGeminiClass_Request_GenerateContent.Create;
  Try
    oRequest.Model := 'gemini-2.5-flash';
    // Define a function
    oFunc := TsgcGeminiClass_Request_FunctionDeclaration.Create;
    oFunc.Name := 'get_weather';
    oFunc.Description := 'Get the current weather in a location';
    oFunc.Parameters :=
      '{"type":"object","properties":{"location":{"type":"string"}}}';
    oRequest.FunctionDeclarations.Add(oFunc);
    oRequest.Contents.Add('user',
      'What is the weather in Madrid?');
    oResponse := Gemini.CreateContent(oRequest);
    Try
      // Check if Gemini wants to call a function
      if oResponse.Candidates[0].Parts[0].FunctionCallName  '' then
      begin
        ShowMessage('Function: ' + oResponse.Candidates[0].Parts[0].FunctionCallName);
        ShowMessage('Args: ' + oResponse.Candidates[0].Parts[0].FunctionCallArgs);
      end;
    Finally
      oResponse.Free;
    End;
  Finally
    oRequest.Free;
  End;
end;

임베딩

텍스트의 고품질 벡터 임베딩을 생성해요. 임베딩은 시맨틱 검색, 문서 클러스터링, 추천 엔진, 분류 작업을 구현하는 데 활용돼요.

// Generate embeddings for a text
var
  vEmbedding: string;
begin
  vEmbedding := Gemini._EmbedContent(
    'text-embedding-004',
    'Delphi is a powerful programming language.');
  ShowMessage(vEmbedding);
end;

완전한 제어를 위해 타입 지정 API를 사용해 원시 임베딩 값 배열에 접근하세요.

var
  oResponse: TsgcGeminiClass_Response_Embedding;
  i: Integer;
begin
  oResponse := Gemini.EmbedContent(
    'text-embedding-004',
    'Delphi is a powerful programming language.');
  Try
    for i := 0 to Length(oResponse.Values) - 1 do
      Memo1.Lines.Add(FloatToStr(oResponse.Values[i]));
  Finally
    oResponse.Free;
  End;
end;

토큰 계산

요청을 전송하기 전에 비용을 정확히 추정하고 컨텍스트 창 예산을 관리하세요.

var
  vTokens: string;
begin
  vTokens := Gemini._CountTokens(
    'gemini-2.5-flash',
    'How many tokens does this message consume?');
  ShowMessage(vTokens);
end;

모델 관리

프로그래밍 방식으로 사용 가능한 Gemini 모델을 조회해요. 모든 모델을 나열하거나 표시 이름, 설명, 토큰 한도를 포함한 특정 모델 ID의 세부 정보를 조회할 수 있어요.

// List all available Gemini models
vModels := Gemini._GetModels;
// Get details for a specific model
vModel := Gemini._GetModel('gemini-2.5-flash');
// Typed API: access model properties directly
var
  oModel: TsgcGeminiClass_Response_Model;
begin
  oModel := Gemini.GetModel('gemini-2.5-flash');
  Try
    ShowMessage('Name: ' + oModel.DisplayName);
    ShowMessage('Input limit: ' + IntToStr(oModel.InputTokenLimit));
    ShowMessage('Output limit: ' + IntToStr(oModel.OutputTokenLimit));
  Finally
    oModel.Free;
  End;
end;

설정 및 옵션

포괄적인 설정 옵션으로 컴포넌트 동작을 세밀하게 조정하세요.

속성 설명
GeminiOptions.ApiKey Google Gemini API 키 (필수)
HttpOptions.ReadTimeout HTTP 읽기 타임아웃(밀리초, 기본값: 60000)
LogOptions.Enabled 요청/응답 로깅 활성화
LogOptions.FileName 요청/응답 캡처용 로그 파일 경로
RetryOptions.Enabled 일시적 오류(429, 503) 시 자동 재시도
RetryOptions.Retries 최대 재시도 횟수(기본값: 3)
RetryOptions.Wait 재시도 간 대기 시간(밀리초, 기본값: 3000)

요청 파라미터

파라미터 설명
Temperature 샘플링 온도(0.0~2.0). 낮을수록 더 결정적이에요.
TopP Nucleus 샘플링(0.0~1.0). 누적 확률 컷오프를 제어해요.
TopK Top-K 샘플링. 토큰 선택을 상위 K개 후보로 제한해요.
MaxOutputTokens 응답의 최대 토큰 수(기본값: 4096).
StopSequences 생성을 중단할 사용자 정의 시퀀스.
ResponseMimeType 출력 형식: JSON은 'application/json', 텍스트는 'text/plain'.
ToolChoice 모델이 호출할 함수를 선택하는 방식을 제어해요.