컨텍스트 캐싱을 사용하면 반복적으로 사용하고 싶은 미리 계산된 입력 토큰을 저장하고 재사용할 수 있습니다(예: 동일한 미디어 파일에 대해 서로 다른 질문을 하는 경우). 사용량에 따라 비용과 속도를 절약할 수 있습니다. 자세한 소개는 컨텍스트 캐싱 가이드를 참고하세요.
메서드: cachedContents.create
CachedContent 리소스를 만듭니다.
엔드포인트
게시 https://generativelanguage.googleapis.com/v1beta/cachedContents요청 본문
요청 본문에 CachedContent
의 인스턴스가 포함됩니다.
contents[]
object (Content
)
선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 캐시할 콘텐츠입니다.
tools[]
object (Tool
)
선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 모델이 다음 응답을 생성하는 데 사용할 수 있는 Tools
목록
expiration
. 이 리소스가 만료되는 시기를 지정합니다. expiration
은 다음 중 하나여야 합니다.
expireTime
string (Timestamp
format)
이 리소스가 만료된 것으로 간주되는 시간의 타임스탬프(UTC)입니다. 이 필드는 입력으로 전송된 항목에 관계없이 항상 출력으로 제공됩니다.
RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z"
및 "2014-10-02T15:01:23.045123456Z"
입니다.
ttl
string (Duration
format)
입력 전용입니다. 이 리소스의 새 TTL입니다(입력만 가능).
소수점 아래가 최대 9자리까지이고 's
'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"
입니다.
name
string
선택사항입니다. 식별자. 캐시된 콘텐츠를 참조하는 리소스 이름입니다. 형식: cachedContents/{id}
displayName
string
선택사항입니다. 변경할 수 없습니다. 캐시된 콘텐츠의 의미 있는 사용자 생성 표시 이름입니다. 최대 128자(유니코드 기준)
model
string
필수 항목입니다. 변경할 수 없습니다. 캐시된 콘텐츠에 사용할 Model
의 이름입니다. 형식: models/{model}
systemInstruction
object (Content
)
선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 개발자가 설정한 시스템 안내 현재 텍스트 전용입니다.
toolConfig
object (ToolConfig
)
선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 도구 구성 이 구성은 모든 도구에서 공유됩니다.
요청 예시
기본
Python
Node.js
Go
Shell
발신자 이름
Python
Node.js
Go
채팅에서 생성된 할 일
Python
Node.js
Go
응답 본문
성공한 경우 응답 본문에 새로 생성된 CachedContent
의 인스턴스가 포함됩니다.
메서드: cachedContents.list
CachedContents를 나열합니다.
엔드포인트
get https://generativelanguage.googleapis.com/v1beta/cachedContents쿼리 매개변수
pageSize
integer
선택사항입니다. 반환할 최대 캐시된 콘텐츠 수입니다. 서비스가 이 값보다 더 적게 반환할 수 있습니다. 지정하지 않으면 일부 기본 항목 (최대 이하)이 반환됩니다. 최댓값은 1,000이며, 1,000을 초과하는 값은 1,000으로 변환됩니다.
pageToken
string
선택사항입니다. 이전 cachedContents.list
호출에서 받은 페이지 토큰입니다. 후속 페이지를 검색하려면 이를 입력합니다.
페이지를 매길 때 cachedContents.list
에 제공된 다른 모든 매개변수는 페이지 토큰을 제공한 호출과 일치해야 합니다.
요청 본문
요청 본문은 비어 있어야 합니다.
응답 본문
CachedContents 목록이 포함된 응답입니다.
성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.
cachedContents[]
object (CachedContent
)
캐시된 콘텐츠의 목록입니다.
nextPageToken
string
다음 페이지를 검색하기 위해 pageToken
으로 전송할 수 있는 토큰입니다. 이 필드를 생략하면 후속 페이지가 표시되지 않습니다.
JSON 표현 |
---|
{
"cachedContents": [
{
object ( |
메서드: cachedContents.get
CachedContent 리소스를 읽습니다.
엔드포인트
get https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}경로 매개변수
name
string
필수 항목입니다. 콘텐츠 캐시 항목을 참조하는 리소스 이름입니다. 형식: cachedContents/{id}
cachedContents/{cachedcontent}
형식을 취합니다.
요청 본문
요청 본문은 비어 있어야 합니다.
요청 예시
Python
Node.js
Go
Shell
응답 본문
성공한 경우 응답 본문에 CachedContent
의 인스턴스가 포함됩니다.
메서드: CacheContents.patch
CachedContent 리소스를 업데이트합니다 (만료만 업데이트 가능).
엔드포인트
패치 https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}
경로 매개변수
cachedContent.name
string
선택사항입니다. 식별자. 캐시된 콘텐츠를 참조하는 리소스 이름입니다. 형식: cachedContents/{id}
cachedContents/{cachedcontent}
형식이 사용됩니다.
쿼리 매개변수
updateMask
string (FieldMask
format)
업데이트할 필드 목록입니다.
정규화된 필드 이름의 쉼표로 구분된 목록입니다. 예: "user.displayName,photo"
요청 본문
요청 본문에 CachedContent
의 인스턴스가 포함됩니다.
expiration
. 이 리소스가 만료되는 시기를 지정합니다. expiration
은 다음 중 하나여야 합니다.
expireTime
string (Timestamp
format)
이 리소스가 만료된 것으로 간주되는 시간의 타임스탬프(UTC)입니다. 이 필드는 입력으로 전송된 항목에 관계없이 항상 출력으로 제공됩니다.
RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z"
및 "2014-10-02T15:01:23.045123456Z"
입니다.
ttl
string (Duration
format)
입력 전용입니다. 이 리소스의 새 TTL입니다(입력만 가능).
소수점 아래가 최대 9자리까지이고 's
'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"
입니다.
name
string
선택사항입니다. 식별자. 캐시된 콘텐츠를 참조하는 리소스 이름입니다. 형식: cachedContents/{id}
요청 예시
Python
Node.js
Go
Shell
응답 본문
성공한 경우 응답 본문에 CachedContent
의 인스턴스가 포함됩니다.
메서드: cachedContents.delete
CachedContent 리소스를 삭제합니다.
엔드포인트
삭제 https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}경로 매개변수
name
string
필수 항목입니다. 콘텐츠 캐시 항목을 참조하는 리소스 이름 형식: cachedContents/{id}
cachedContents/{cachedcontent}
형식입니다.
요청 본문
요청 본문은 비어 있어야 합니다.
요청 예시
Python
Node.js
Go
Shell
응답 본문
성공한 경우 응답 본문은 비어 있습니다.
REST 리소스: cacheContents
- 리소스: CachedContent
- 콘텐츠
- 부분
- Blob
- FunctionCall
- FunctionResponse
- FileData
- ExecutableCode
- 언어
- CodeExecutionResult
- 결과
- 도구
- FunctionDeclaration
- 스키마
- 유형
- GoogleSearchRetrieval
- DynamicRetrievalConfig
- 모드
- CodeExecution
- ToolConfig
- FunctionCallingConfig
- 모드
- UsageMetadata
- 메서드
리소스: CachedContent
사전 처리되었으며 이후 GenerativeService 요청에 사용할 수 있는 콘텐츠입니다.
캐시된 콘텐츠는 생성된 모델과 함께만 사용할 수 있습니다.
contents[]
object (Content
)
선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 캐시할 콘텐츠입니다.
tools[]
object (Tool
)
선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 모델이 다음 응답을 생성하는 데 사용할 수 있는 Tools
목록
createTime
string (Timestamp
format)
출력 전용입니다. 캐시 항목의 생성 시간입니다.
RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z"
및 "2014-10-02T15:01:23.045123456Z"
입니다.
updateTime
string (Timestamp
format)
출력 전용입니다. 캐시 항목이 마지막으로 업데이트된 시간(UTC 시간)입니다.
RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z"
및 "2014-10-02T15:01:23.045123456Z"
입니다.
usageMetadata
object (UsageMetadata
)
출력 전용입니다. 캐시된 콘텐츠의 사용에 관한 메타데이터입니다.
expiration
. 이 리소스가 만료되는 시점을 지정합니다. expiration
은 다음 중 하나여야 합니다.
expireTime
string (Timestamp
format)
이 리소스가 만료된 것으로 간주되는 시간의 타임스탬프(UTC)입니다. 이 필드는 입력으로 전송된 항목에 관계없이 항상 출력으로 제공됩니다.
RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z"
및 "2014-10-02T15:01:23.045123456Z"
입니다.
ttl
string (Duration
format)
입력 전용입니다. 이 리소스의 새 TTL입니다(입력만 가능).
소수점 아래가 최대 9자리까지이고 's
'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"
입니다.
name
string
선택사항입니다. 식별자. 캐시된 콘텐츠를 참조하는 리소스 이름입니다. 형식: cachedContents/{id}
displayName
string
선택사항입니다. 변경할 수 없습니다. 캐시된 콘텐츠의 의미 있는 사용자 생성 표시 이름입니다. 최대 128자(유니코드 기준)
model
string
필수 항목입니다. 변경할 수 없습니다. 캐시된 콘텐츠에 사용할 Model
의 이름입니다. 형식: models/{model}
systemInstruction
object (Content
)
선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 개발자가 설정한 시스템 안내 현재 텍스트 전용입니다.
toolConfig
object (ToolConfig
)
선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 도구 구성 이 구성은 모든 도구에 공유됩니다.
JSON 표현 |
---|
{ "contents": [ { object ( |
콘텐츠
메시지의 여러 부분으로 구성된 콘텐츠를 포함하는 구조화된 데이터의 기본 유형입니다.
Content
에는 Content
의 생산자를 지정하는 role
필드와 메시지 대화의 콘텐츠가 포함된 멀티파트 데이터가 포함된 parts
필드가 포함됩니다.
parts[]
object (Part
)
단일 메시지를 구성하는 순서가 지정된 Parts
입니다. 부분마다 MIME 유형이 다를 수 있습니다.
role
string
선택사항입니다. 콘텐츠 제작자 'user' 또는 'model'이어야 합니다.
멀티턴 대화에 설정하면 유용하며, 그렇지 않은 경우에는 비워 두거나 설정하지 않아도 됩니다.
JSON 표현 |
---|
{
"parts": [
{
object ( |
부품
멀티 파트 Content
메시지의 일부인 미디어를 포함하는 데이터 유형입니다.
Part
는 연결된 데이터 유형이 있는 데이터로 구성됩니다. Part
는 Part.data
에서 허용되는 유형 중 하나만 포함할 수 있습니다.
inlineData
필드가 원시 바이트로 채워진 경우 Part
에는 미디어의 유형과 하위유형을 식별하는 고정된 IANA MIME 유형이 있어야 합니다.
통합 필드 data
.
data
는 다음 중 하나여야 합니다.
text
string
인라인 텍스트
inlineData
object (Blob
)
인라인 미디어 바이트.
functionCall
object (FunctionCall
)
모델에서 반환한 예측된 FunctionCall
로, 인수와 그 값과 함께 FunctionDeclaration.name
를 나타내는 문자열이 포함됩니다.
functionResponse
object (FunctionResponse
)
FunctionDeclaration.name
을 나타내는 문자열과 함수의 출력이 포함된 구조화된 JSON 객체가 포함된 FunctionCall
의 결과 출력은 모델의 컨텍스트로 사용됩니다.
fileData
object (FileData
)
URI 기반 데이터
executableCode
object (ExecutableCode
)
실행할 모델에서 생성한 코드입니다.
codeExecutionResult
object (CodeExecutionResult
)
ExecutableCode
실행 결과
JSON 표현 |
---|
{ // Union field |
blob
원시 미디어 바이트입니다.
텍스트는 원시 바이트로 전송해서는 안 되며 'text' 필드를 사용해야 합니다.
mimeType
string
소스 데이터의 IANA 표준 MIME 유형입니다. 예: - image/png - image/jpeg 지원되지 않는 MIME 유형을 제공하면 오류가 반환됩니다. 지원되는 유형의 전체 목록은 지원되는 파일 형식을 참고하세요.
data
string (bytes format)
미디어 형식의 원시 바이트입니다.
base64 인코딩 문자열입니다.
JSON 표현 |
---|
{ "mimeType": string, "data": string } |
FunctionCall
인수와 해당 값이 포함된 FunctionDeclaration.name
을 나타내는 문자열을 포함하는 모델에서 반환된 예측된 FunctionCall
입니다.
name
string
필수 항목입니다. 호출하려는 함수의 이름입니다. a~z, A~Z, 0~9이거나 밑줄과 대시를 포함해야 하며 최대 길이는 63자(영문 기준)입니다.
args
object (Struct
format)
선택사항입니다. JSON 객체 형식의 함수 매개변수와 값입니다.
JSON 표현 |
---|
{ "name": string, "args": { object } } |
FunctionResponse
FunctionDeclaration.name
을 나타내는 문자열과 함수의 출력이 포함된 구조화된 JSON 객체가 포함된 FunctionCall
의 결과 출력은 모델의 컨텍스트로 사용됩니다. 여기에는 모델 예측을 기반으로 한 FunctionCall
의 결과가 포함되어야 합니다.
name
string
필수 항목입니다. 호출하려는 함수의 이름입니다. a~z, A~Z, 0~9이거나 밑줄과 대시를 포함해야 하며 최대 63자 길이입니다.
response
object (Struct
format)
필수 항목입니다. JSON 객체 형식의 함수 응답입니다.
JSON 표현 |
---|
{ "name": string, "response": { object } } |
FileData
URI 기반 데이터
mimeType
string
선택사항입니다. 소스 데이터의 IANA 표준 MIME 유형입니다.
fileUri
string
필수 항목입니다. URI
JSON 표현 |
---|
{ "mimeType": string, "fileUri": string } |
ExecutableCode
언어
생성된 코드에 지원되는 프로그래밍 언어입니다.
열거형 | |
---|---|
LANGUAGE_UNSPECIFIED |
지정되지 않은 언어 이 값은 사용하면 안 됩니다. |
PYTHON |
Python 3.10 이상, NumPy 및 Simpy 사용 가능 |
CodeExecutionResult
결과
코드 실행의 가능한 결과의 열거형입니다.
열거형 | |
---|---|
OUTCOME_UNSPECIFIED |
지정되지 않은 상태입니다. 이 값은 사용하면 안 됩니다. |
OUTCOME_OK |
코드 실행이 완료되었습니다. |
OUTCOME_FAILED |
코드 실행이 완료되었지만 오류가 발생했습니다. stderr 에는 이유가 포함되어야 합니다. |
OUTCOME_DEADLINE_EXCEEDED |
코드 실행이 너무 오래 실행되어 취소되었습니다. 부분적인 출력이 표시될 수도 있고 아닐 수도 있습니다. |
도구
모델이 응답을 생성하는 데 사용할 수 있는 도구 세부정보입니다.
Tool
는 시스템이 모델의 지식과 범위를 벗어나 외부 시스템과 상호작용하여 작업 또는 작업 집합을 수행할 수 있도록 하는 코드 조각입니다.
functionDeclarations[]
object (FunctionDeclaration
)
선택사항입니다. 모델에서 사용할 수 있고 함수 호출에 사용할 수 있는 FunctionDeclarations
목록입니다.
모델 또는 시스템이 함수를 실행하지 않습니다. 대신 정의된 함수는 실행을 위해 클라이언트 측에 인수가 있는 FunctionCall
로 반환될 수 있습니다. 모델은 응답에 FunctionCall
를 채움으로써 이러한 함수의 하위 집합을 호출하기로 결정할 수 있습니다. 다음 대화 턴에는 다음 모델 턴의 Content.role
'함수' 생성 컨텍스트가 포함된 FunctionResponse
가 포함될 수 있습니다.
googleSearchRetrieval
object (GoogleSearchRetrieval
)
선택사항입니다. Google 검색을 기반으로 하는 검색 도구입니다.
codeExecution
object (CodeExecution
)
선택사항입니다. 모델이 생성의 일부로 코드를 실행하도록 합니다.
JSON 표현 |
---|
{ "functionDeclarations": [ { object ( |
FunctionDeclaration
OpenAPI 3.03 사양에서 정의된 함수 선언의 구조화된 표현입니다. 이 선언에는 함수 이름과 매개변수가 포함됩니다. 이 FunctionDeclaration은 모델에서 Tool
로 사용하고 클라이언트에서 실행할 수 있는 코드 블록을 나타냅니다.
name
string
필수 항목입니다. 함수 이름입니다. a~z, A~Z, 0~9이거나 밑줄과 대시를 포함해야 하며 최대 길이는 63자(영문 기준)입니다.
description
string
필수 항목입니다. 함수에 대한 간단한 설명입니다.
parameters
object (Schema
)
선택사항입니다. 이 함수의 매개변수를 설명합니다. Open API 3.03 매개변수 객체 문자열 키를 반영합니다. 매개변수의 이름입니다. 매개변수 이름은 대소문자를 구분합니다. 스키마 값: 매개변수에 사용되는 유형을 정의하는 스키마입니다.
JSON 표현 |
---|
{
"name": string,
"description": string,
"parameters": {
object ( |
스키마
Schema
객체를 사용하면 입력 및 출력 데이터 유형을 정의할 수 있습니다. 이러한 유형은 객체일 수 있지만 원시 유형과 배열도 될 수 있습니다. OpenAPI 3.0 스키마 객체의 선택된 하위 집합을 나타냅니다.
type
enum (Type
)
필수 항목입니다. 데이터 유형
format
string
선택사항입니다. 데이터 형식입니다. 이는 기본 데이터 유형에만 사용됩니다. 지원되는 형식: NUMBER 유형: float, double의 경우 INTEGER 유형: int32, 문자열의 경우 int64 유형: enum
description
string
선택사항입니다. 매개변수에 대한 간단한 설명입니다. 여기에는 사용 예시가 포함될 수 있습니다. 매개변수 설명은 마크다운 형식일 수 있습니다.
nullable
boolean
선택사항입니다. null 값을 나타냅니다.
enum[]
string
선택사항입니다. enum 형식의 가능한 Type.STRING 요소 값입니다. 예를 들어 열거형 방향을 다음과 같이 정의할 수 있습니다. {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
maxItems
string (int64 format)
선택사항입니다. Type.ARRAY의 최대 요소 수입니다.
minItems
string (int64 format)
선택사항입니다. Type.ARRAY의 요소 최솟값입니다.
properties
map (key: string, value: object (Schema
))
선택사항입니다. Type.OBJECT의 속성입니다.
"key": value
쌍 목록을 포함하는 객체입니다. 예: { "name": "wrench", "mass": "1.3kg", "count": "3" }
required[]
string
선택사항입니다. Type.OBJECT의 필수 속성입니다.
items
object (Schema
)
선택사항입니다. Type.ARRAY 요소의 스키마입니다.
유형
Type에는 https://spec.openapis.org/oas/v3.0.3#data-types에 정의된 OpenAPI 데이터 유형 목록이 포함됩니다.
열거형 | |
---|---|
TYPE_UNSPECIFIED |
지정되지 않았으며 사용해서는 안 됩니다. |
STRING |
문자열 유형입니다. |
NUMBER |
숫자 유형입니다. |
INTEGER |
정수 유형입니다. |
BOOLEAN |
불리언 유형입니다. |
ARRAY |
배열 유형입니다. |
OBJECT |
객체 유형입니다. |
GoogleSearchRetrieval
그라운딩을 위해 공개 웹 데이터를 검색하는 도구로, Google에서 제공합니다.
dynamicRetrievalConfig
object (DynamicRetrievalConfig
)
지정된 소스의 동적 검색 구성을 지정합니다.
JSON 표현 |
---|
{
"dynamicRetrievalConfig": {
object ( |
DynamicRetrievalConfig
모드
동적 검색에 사용할 예측자의 모드입니다.
열거형 | |
---|---|
MODE_UNSPECIFIED |
항상 검색을 트리거합니다. |
MODE_DYNAMIC |
시스템에서 필요하다고 판단하는 경우에만 검색을 실행합니다. |
CodeExecution
이 유형에는 필드가 없습니다.
모델에서 생성된 코드를 실행하고 결과를 모델에 자동으로 반환하는 도구입니다.
이 도구를 사용할 때만 생성되는 ExecutableCode
및 CodeExecutionResult
도 참고하세요.
ToolConfig
요청에서 Tool
사용을 지정하기 위한 매개변수가 포함된 도구 구성입니다.
functionCallingConfig
object (FunctionCallingConfig
)
선택사항입니다. 함수 호출 구성
JSON 표현 |
---|
{
"functionCallingConfig": {
object ( |
FunctionCallingConfig
함수 호출 동작을 지정하기 위한 구성입니다.
mode
enum (Mode
)
선택사항입니다. 함수 호출을 실행해야 하는 모드를 지정합니다. 지정하지 않으면 기본값은 AUTO로 설정됩니다.
allowedFunctionNames[]
string
선택사항입니다. 제공된 경우 모델이 호출할 함수를 제한하는 함수 이름 집합입니다.
모드가 ANY인 경우에만 설정해야 합니다. 함수 이름은 [FunctionDeclaration.name]과 일치해야 합니다. 모드를 ANY로 설정하면 모델이 제공된 함수 이름 세트에서 함수 호출을 예측합니다.
JSON 표현 |
---|
{
"mode": enum ( |
모드
실행 모드를 정의하여 함수 호출의 실행 동작을 정의합니다.
열거형 | |
---|---|
MODE_UNSPECIFIED |
지정되지 않은 함수 호출 모드입니다. 이 값은 사용하면 안 됩니다. |
AUTO |
기본 모델 동작으로, 모델이 함수 호출 또는 자연어 응답을 예측하도록 결정합니다. |
ANY |
모델이 항상 함수 호출만 예측하도록 제한됩니다. 'allowedFunctionNames'가 설정되면 예측 함수 호출이 'allowedFunctionNames' 중 하나로 제한됩니다. 그러지 않으면 예측 함수 호출은 제공된 'functionDeclarations' 중 하나가 됩니다. |
NONE |
모델이 함수 호출을 예측하지 않습니다. 모델 동작은 함수 선언을 전달하지 않는 경우와 동일합니다. |
UsageMetadata
캐시된 콘텐츠 사용에 관한 메타데이터입니다.
totalTokenCount
integer
캐시된 콘텐츠에서 사용하는 총 토큰 수입니다.
JSON 표현 |
---|
{ "totalTokenCount": integer } |