Batch Mode

Gemini API는 단일 호출로 여러 요청을 처리할 수 있는 일괄 모드를 지원합니다. 자세한 내용은 일괄 모드 가이드를 참고하세요.

메서드: models.batchGenerateContent

일괄 처리를 위해 models.generateContent 요청을 대기열에 추가합니다.

엔드포인트

게시물 https://generativelanguage.googleapis.com/v1beta/{batch.model=models/*}:batchGenerateContent

경로 매개변수

batch.model string

필수입니다. 완료를 생성하는 데 사용할 Model의 이름입니다.

형식: models/{model} models/{model} 형식이 사용됩니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

필드
batch.name string

출력 전용입니다. 식별자. 일괄 처리의 리소스 이름입니다.

형식: batches/{batchId}

batch.displayName string

필수입니다. 이 배치에 사용자가 정의한 이름입니다.

batch.inputConfig object (InputConfig)

필수입니다. 일괄 처리가 실행되는 인스턴스의 입력 구성입니다.

batch.output object (GenerateContentBatchOutput)

출력 전용입니다. 일괄 요청의 출력입니다.

batch.createTime string (Timestamp format)

출력 전용입니다. 배치가 생성된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

batch.endTime string (Timestamp format)

출력 전용입니다. 일괄 처리가 완료된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

batch.updateTime string (Timestamp format)

출력 전용입니다. 배치가 마지막으로 업데이트된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

batch.batchStats object (BatchStats)

출력 전용입니다. 배치에 관한 통계입니다.

batch.state enum (BatchState)

출력 전용입니다. 배치의 상태입니다.

batch.priority string (int64 format)

선택사항입니다. 배치의 우선순위입니다. 우선순위 값이 높은 일괄 처리는 우선순위 값이 낮은 일괄 처리보다 먼저 처리됩니다. 음수 값을 사용할 수 있습니다. 기본값은 0입니다.

응답 본문

성공한 경우 응답 본문에 Operation의 인스턴스가 포함됩니다.

GenerateContentRequest

모델에서 완성 텍스트를 생성하도록 요청합니다.

Fields
model string

필수입니다. 완료를 생성하는 데 사용할 Model의 이름입니다.

형식: models/{model}

contents[] object (Content)

필수입니다. 모델과의 현재 대화 콘텐츠입니다.

싱글턴 쿼리의 경우 이는 단일 인스턴스입니다. 채팅과 같은 멀티턴 쿼리의 경우 이는 대화 기록과 최근 요청이 포함된 반복 필드입니다.

tools[] object (Tool)

선택사항입니다. Model이 다음 대답을 생성하는 데 사용할 수 있는 Tools 목록입니다.

Tool은 시스템이 Model의 지식과 범위를 벗어나 외부 시스템과 상호작용하여 작업 또는 작업 집합을 수행할 수 있도록 하는 코드 조각입니다. 지원되는 Tool는 Function 및 codeExecution입니다. 자세한 내용은 함수 호출 및 코드 실행 가이드를 참고하세요.

toolConfig object (ToolConfig)

선택사항입니다. 요청에 지정된 Tool의 도구 구성입니다. 사용 예시는 함수 호출 가이드를 참고하세요.

safetySettings[] object (SafetySetting)

선택사항입니다. 안전하지 않은 콘텐츠를 차단하기 위한 고유한 SafetySetting 인스턴스 목록입니다.

이 규칙은 GenerateContentRequest.contents 및 GenerateContentResponse.candidates에 적용됩니다. 각 SafetyCategory 유형에 설정이 두 개 이상 있으면 안 됩니다. API는 이러한 설정에 의해 설정된 기준을 충족하지 않는 콘텐츠와 응답을 차단합니다. 이 목록은 safetySettings에 지정된 각 SafetyCategory의 기본 설정을 재정의합니다. 목록에 제공된 특정 SafetyCategory에 대한 SafetySetting가 없는 경우 API는 해당 카테고리의 기본 안전 설정을 사용합니다. HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY 유해 카테고리가 지원됩니다. 사용 가능한 안전 설정에 관한 자세한 내용은 가이드를 참고하세요. 안전 가이드를 참고하여 AI 애플리케이션에 안전 고려사항을 통합하는 방법도 알아보세요.

systemInstruction object (Content)

선택사항입니다. 개발자가 설정한 시스템 요청 사항 현재는 텍스트만 지원됩니다.

generationConfig object (GenerationConfig)

선택사항입니다. 모델 생성 및 출력의 구성 옵션입니다.

cachedContent string

선택사항입니다. 예측을 제공하기 위한 컨텍스트로 사용하기 위해 캐시된 콘텐츠의 이름입니다. 형식: cachedContents/{cachedContent}

JSON 표현 
{
  "model": string,
  "contents": [
    {
      object (Content)
    }
  ],
  "tools": [
    {
      object (Tool)
    }
  ],
  "toolConfig": {
    object (ToolConfig)
  },
  "safetySettings": [
    {
      object (SafetySetting)
    }
  ],
  "systemInstruction": {
    object (Content)
  },
  "generationConfig": {
    object (GenerationConfig)
  },
  "cachedContent": string
}

GenerateContentBatch

GenerateContent 요청의 일괄 처리를 나타내는 리소스입니다.

Fields
model string

필수입니다. 완료를 생성하는 데 사용할 Model의 이름입니다.

형식: models/{model}

name string

출력 전용입니다. 식별자. 일괄 처리의 리소스 이름입니다.

형식: batches/{batchId}

displayName string

필수입니다. 이 배치에 사용자가 정의한 이름입니다.

inputConfig object (InputConfig)

필수입니다. 일괄 처리가 실행되는 인스턴스의 입력 구성입니다.

output object (GenerateContentBatchOutput)

출력 전용입니다. 일괄 요청의 출력입니다.

createTime string (Timestamp format)

출력 전용입니다. 배치가 생성된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

endTime string (Timestamp format)

출력 전용입니다. 일괄 처리가 완료된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

updateTime string (Timestamp format)

출력 전용입니다. 배치가 마지막으로 업데이트된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

batchStats object (BatchStats)

출력 전용입니다. 배치에 관한 통계입니다.

state enum (BatchState)

출력 전용입니다. 배치의 상태입니다.

priority string (int64 format)

선택사항입니다. 배치의 우선순위입니다. 우선순위 값이 높은 일괄 처리는 우선순위 값이 낮은 일괄 처리보다 먼저 처리됩니다. 음수 값을 사용할 수 있습니다. 기본값은 0입니다.

JSON 표현 
{
  "model": string,
  "name": string,
  "displayName": string,
  "inputConfig": {
    object (InputConfig)
  },
  "output": {
    object (GenerateContentBatchOutput)
  },
  "createTime": string,
  "endTime": string,
  "updateTime": string,
  "batchStats": {
    object (BatchStats)
  },
  "state": enum (BatchState),
  "priority": string
}

InputConfig

일괄 요청의 입력을 구성합니다.

필드
source Union type
필수입니다. 입력 소스입니다. source는 다음 중 하나여야 합니다.
fileName string

입력 요청이 포함된 File의 이름입니다.

requests object (InlinedRequests)

일괄 처리할 요청입니다.

JSON 표현 
{

  // source
  "fileName": string,
  "requests": {
    object (InlinedRequests)
  }
  // Union type
}

InlinedRequests

일괄 생성 요청의 일부로 제공된 경우 일괄로 처리할 요청입니다.

Fields
requests[] object (InlinedRequest)

필수입니다. 일괄 처리할 요청입니다.

JSON 표현 
{
  "requests": [
    {
      object (InlinedRequest)
    }
  ]
}

InlinedRequest

일괄 처리할 요청입니다.

Fields
request object (GenerateContentRequest)

필수입니다. 일괄 처리할 요청입니다.

metadata object (Struct format)

선택사항입니다. 요청과 연결할 메타데이터입니다.

JSON 표현 
{
  "request": {
    object (GenerateContentRequest)
  },
  "metadata": {
    object
  }
}

GenerateContentBatchOutput

일괄 요청의 출력입니다. 이는 BatchGenerateContentResponse 또는 GenerateContentBatch.output 필드에 반환됩니다.

필드
output Union type
일괄 요청의 출력입니다. output는 다음 중 하나여야 합니다.
responsesFile string

출력 전용입니다. 응답이 포함된 파일의 파일 ID입니다. 파일은 한 줄에 하나의 대답이 있는 JSONL 파일입니다. 대답은 JSON 형식으로 지정된 GenerateContentResponse 메시지입니다. 대답은 입력 요청과 동일한 순서로 작성됩니다.

inlinedResponses object (InlinedResponses)

출력 전용입니다. 배치에 있는 요청에 대한 응답입니다. 인라인 요청을 사용하여 일괄이 빌드된 경우 반환됩니다. 대답은 입력 요청과 동일한 순서로 제공됩니다.

JSON 표현 
{

  // output
  "responsesFile": string,
  "inlinedResponses": {
    object (InlinedResponses)
  }
  // Union type
}

InlinedResponses

배치에 있는 요청에 대한 응답입니다.

Fields
inlinedResponses[] object (InlinedResponse)

출력 전용입니다. 배치에 있는 요청에 대한 응답입니다.

JSON 표현 
{
  "inlinedResponses": [
    {
      object (InlinedResponse)
    }
  ]
}

InlinedResponse

배치의 단일 요청에 대한 응답입니다.

Fields
metadata object (Struct format)

출력 전용입니다. 요청과 연결된 메타데이터입니다.

output Union type
요청의 출력입니다. output는 다음 중 하나여야 합니다.
error object (Status)

출력 전용입니다. 요청을 처리하는 중에 발생한 오류입니다.

response object (GenerateContentResponse)

출력 전용입니다. 요청에 대한 응답입니다.

JSON 표현 
{
  "metadata": {
    object
  },

  // output
  "error": {
    object (Status)
  },
  "response": {
    object (GenerateContentResponse)
  }
  // Union type
}

BatchStats

배치에 관한 통계입니다.

Fields
requestCount string (int64 format)

출력 전용입니다. 배치의 요청 수입니다.

successfulRequestCount string (int64 format)

출력 전용입니다. 성공적으로 처리된 요청의 수입니다.

failedRequestCount string (int64 format)

출력 전용입니다. 처리되지 않은 요청 수입니다.

pendingRequestCount string (int64 format)

출력 전용입니다. 아직 처리 대기 중인 요청 수입니다.

JSON 표현 
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}

BatchState

배치의 상태입니다.

열거형
BATCH_STATE_UNSPECIFIED 일괄 상태가 지정되지 않았습니다.
BATCH_STATE_PENDING 서비스가 배치를 실행할 준비를 하고 있습니다.
BATCH_STATE_RUNNING 배치가 진행 중입니다.
BATCH_STATE_SUCCEEDED 일괄 처리가 완료되었습니다.
BATCH_STATE_FAILED 배치가 실패했습니다.
BATCH_STATE_CANCELLED 일괄 처리가 취소되었습니다.
BATCH_STATE_EXPIRED 배치가 만료되었습니다.

REST 리소스: batches

리소스: 작업

이 리소스는 네트워크 API 호출의 결과인 장기 실행 작업을 나타냅니다.

Fields
name string

서버에 할당된 이름으로, 해당 이름을 최초로 반환한 서비스 내에서만 고유합니다. 기본 HTTP 매핑을 사용하는 경우 name은 operations/{unique_id}로 끝나는 리소스 이름이어야 합니다.

metadata object

작업과 관련된 서비스별 메타데이터입니다. 일반적으로 진행률 정보 및 생성 시간과 같은 일반 메타데이터가 포함됩니다. 일부 서비스는 이러한 메타데이터를 제공하지 않을 수 있습니다. 장기 실행 작업을 반환하는 메소드는 메타데이터 유형이 있는 경우 이를 문서화해야 합니다.

임의 유형의 필드를 포함하는 객체입니다. 추가 필드 "@type"은 유형을 식별하는 URI를 포함합니다. 예: { "id": 1234, "@type": "types.example.com/standard/id" }

done boolean

값이 false이면 작업이 아직 진행 중이라는 의미입니다. true이면 작업이 완료된 것이며, error 또는 response를 사용할 수 있습니다.

result Union type
작업 결과로, error 또는 유효한 response일 수 있습니다. done == false이면 error와 response가 모두 설정되지 않습니다. done == true이면 error 또는 response 중 정확히 하나를 설정할 수 있습니다. 일부 서비스는 결과를 제공하지 않을 수 있습니다. result은 다음 중 하나여야 합니다.
error object (Status)

실패하거나 취소된 작업의 오류 결과입니다.

response object

정상적인 성공한 작업 응답입니다. Delete와 같이 원래 메서드가 성공 시 데이터를 반환하지 않는 경우 응답은 google.protobuf.Empty입니다. 원래 메서드가 표준 Get/Create/Update이면 응답은 리소스여야 합니다. 다른 메서드의 경우 응답은 XxxResponse 유형이어야 하며, 여기에서 Xxx는 원래 메서드의 이름입니다. 예를 들어 원래 메서드 이름이 TakeSnapshot()이면 추론된 응답 유형은 TakeSnapshotResponse입니다.

임의 유형의 필드를 포함하는 객체입니다. 추가 필드 "@type"은 유형을 식별하는 URI를 포함합니다. 예: { "id": 1234, "@type": "types.example.com/standard/id" }

JSON 표현 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

메서드: batches.get

장기 실행 작업의 최신 상태를 가져옵니다. 클라이언트는 이 메서드를 사용하여 API 서비스가 권장하는 간격으로 작업 결과를 폴링할 수 있습니다.

엔드포인트

get https://generativelanguage.googleapis.com/v1beta/{name=batches/*}

경로 매개변수

name string

작업 리소스의 이름입니다. batches/{batches} 형식이 사용됩니다.

요청 본문

요청 본문은 비어 있어야 합니다.

응답 본문

성공한 경우 응답 본문에 Operation의 인스턴스가 포함됩니다.

메서드: batches.list

요청 시 지정된 필터와 일치하는 작업을 나열합니다. 서버에서 이 메서드를 지원하지 않으면 UNIMPLEMENTED가 반환됩니다.

엔드포인트

get https://generativelanguage.googleapis.com/v1beta/{name=batches}

경로 매개변수

name string

작업의 상위 리소스 이름입니다. batches 형식이 사용됩니다.

쿼리 매개변수

filter string

표준 목록 필터입니다.

pageSize integer

표준 목록 페이지 크기입니다.

pageToken string

표준 목록 페이지 토큰입니다.

요청 본문

요청 본문은 비어 있어야 합니다.

응답 본문

성공한 경우 응답 본문에 ListOperationsResponse의 인스턴스가 포함됩니다.

메서드: batches.cancel

장기 실행 작업에 대한 비동기 취소를 시작합니다. 서버는 작업이 취소되도록 최선을 다하지만 성공한다고 보장되지 않습니다. 서버에서 이 메서드를 지원하지 않으면 google.rpc.Code.UNIMPLEMENTED가 반환됩니다. 클라이언트는 Operations.GetOperation 또는 다른 메서드를 사용하여 취소가 성공했는지 또는 취소에도 불구하고 작업이 완료되었는지 여부를 확인할 수 있습니다. 취소가 성공하면 작업은 삭제되지 않고 대신 Operation.error 값을 갖는 작업이 되며 google.rpc.Status.code가 1로 설정됩니다. 이 값은 Code.CANCELLED에 해당합니다.

엔드포인트

게시물 https://generativelanguage.googleapis.com/v1beta/{name=batches/*}:cancel

경로 매개변수

name string

취소할 작업 리소스의 이름입니다. batches/{batches} 형식이 사용됩니다.

요청 본문

요청 본문은 비어 있어야 합니다.

응답 본문

성공하면 응답 본문은 빈 JSON 객체입니다.

메서드: batches.delete

장기 실행 작업을 삭제합니다. 이 메소드는 클라이언트가 작업 결과에 더 이상 관심이 없음을 나타냅니다. 작업을 취소하지는 않습니다. 서버에서 이 메서드를 지원하지 않으면 google.rpc.Code.UNIMPLEMENTED가 반환됩니다.

엔드포인트

delete https://generativelanguage.googleapis.com/v1beta/{name=batches/*}

경로 매개변수

name string

삭제할 작업 리소스의 이름입니다. batches/{batches} 형식이 사용됩니다.

요청 본문

요청 본문은 비어 있어야 합니다.

응답 본문

성공하면 응답 본문은 빈 JSON 객체입니다.