이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
이 페이지에서는 API 프록시를 YAML의 Apigee 기능 템플릿으로 정의하고 Google Cloud CLI로 배포하는 방법을 보여줍니다. 먼저 간단한 프록시를 빌드한 후 Gemini 모델을 프런트엔드하는 더 완전한 예시를 빌드합니다.
배경은 YAML로 프록시 구성을 참조하세요. 전체 스키마는 API 프록시 YAML 구성 참조를 확인하세요.
시작하기 전에
- 프록시가 Gemini 모델과 통신할 수 있도록 Google Cloud 프로젝트에서 Vertex AI API 를 사용 설정합니다.
gcloud services enable aiplatform.googleapis.com
- Google Cloud CLI를 설치하고 초기화합니다 .
- 이 가이드에서 사용되는 명령어에 액세스하려면 gcloud 베타 구성요소를 설치합니다.
gcloud components install beta
- Apigee 조직과 환경이 하나 이상 있어야 합니다. 조직 및 환경 이름을 기록해 둡니다. 예시에서는 ORG 및 ENV를 자리표시자로 사용합니다. 2부의 AI 게이트웨이에는 추가로 중간 또는 종합 환경 (기본 환경이 아님)이 필요합니다. Apigee 환경 유형을 참조하세요.
- 필수 권한이 있는지 확인합니다.
- API 프록시를 가져오기 (만들기): API 관리자 역할
(
roles/apigee.apiAdmin) 또는apigee.proxies.create를 부여하는 동등한 역할 - API 프록시 배포: 환경 관리자 (
roles/apigee.environmentAdmin) 대상 환경 및 API 리더 (roles/apigee.apiReaderV2) 프로젝트 수준 - 2부 6단계에서 API 키를 생성하는 API 제품, 개발자, 앱을 만들려면 API 관리자 (
roles/apigee.apiAdmin) 및 개발자 관리자 (roles/apigee.developerAdmin)가 필요합니다. 전체 역할 목록은 Apigee 역할을 참조하세요.
- API 프록시를 가져오기 (만들기): API 관리자 역할
(
1부: 간단한 API 프록시 만들기
이 섹션에서는 요청을 Apigee 모의 타겟 서비스로 전달하고 비율 제한을 적용하는 프록시를 만듭니다.
1단계: 템플릿 만들기
템플릿 은 배포하는 파일입니다. 프록시의 기본 경로, 경로, 백엔드 타겟을 정의하고 포함할 기능 을 나열합니다.
프록시의 디렉터리를 만든 후 hello-proxy.yaml이라는 파일을 만듭니다.
gateway: apigee schemaVersion: 1.0.0 name: hello-proxy type: template description: A simple proxy to the Apigee mock target, protected by a rate limit. features: - spike-arrest.yaml endpoints: - name: default basePath: /hello routes: - name: default target: default targets: - name: default url: https://mocktarget.apigee.net
이 템플릿은 다음을 정의합니다.
- 기본 경로가
/hello인 엔드포인트 입니다. 클라이언트는 이 경로에서 프록시를 호출합니다. - route가
default라는 타겟으로 요청을 보내는 **경로** 입니다. - 백엔드 URL을 가리키는 타겟 입니다.
- 다음에 만드는 기능
spike-arrest.yaml입니다.
2단계: 기능 만들기
기능 은 정책을 보유하는 재사용 가능한 구성 단위입니다. 템플릿은 정책을 직접 포함할 수 없으므로 비율 제한 정책은 기능에 있습니다.
템플릿과 동일한 디렉터리에서 spike-arrest.yaml이라는 파일을 만듭니다.
gateway: apigee schemaVersion: 1.0.0 name: spike-arrest displayName: Spike Arrest type: feature description: Protects the backend by smoothing traffic spikes. categories: - traffic parameters: - name: RATE displayName: RATE description: Maximum request rate, for example 30ps (per second) or 100pm (per minute). default: 30ps examples: - 30ps - 100pm defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: SA-SpikeArrest policies: - name: SA-SpikeArrest type: SpikeArrest content: SpikeArrest: metadata: name: SA-SpikeArrest enabled: "true" continueOnError: "false" DisplayName: SA-SpikeArrest Rate: "{RATE}"
이 기능은 다음과 같습니다.
- 요청 비율을 제한하는 SpikeArrest 정책을 정의합니다.
defaultEndpoint.flows를 사용하여 정책을 요청 PreFlow에 추가하므로 모든 요청에서 실행됩니다.- 프록시가 컴파일될 때 기본값
(
30ps)이{RATE}로 대체되는 매개변수RATE를 선언합니다.
3단계: 프록시 가져오기
템플릿을 가져와 API 프록시 버전을 만듭니다. 파일이 포함된 디렉터리에서 이 명령어를 실행합니다.
gcloud beta apigee apis import hello-proxy \
--from-template=hello-proxy.yaml \
--organization=ORGCLI는 템플릿과 기능을 API 프록시 번들로 컴파일하고 업로드한 후 새 프록시 버전을 출력합니다. 가져오기는 버전을 만들지만 배포하지는 않습니다.
4단계: 프록시 배포
환경에 버전을 배포합니다.
gcloud apigee apis deploy \
--api=hello-proxy \
--environment=ENV \
--organization=ORG기본적으로 이 명령어는 최신 버전을 배포합니다. 특정
버전을 배포하려면 해당 번호를 첫 번째 인수로 전달합니다(예:
gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV).
동일한 기본 경로에 다른 프록시가 이미 배포된 경우 다운타임 없이 이를 대체하도록 --override를 추가합니다.
5단계: 프록시 호출
네트워크를 통해 배포된 프록시를 호출하려면 환경이 라우팅 가능한 호스트 이름이 있는 환경 그룹 에 연결되어야 합니다. 조직을 방금 만든 경우 프록시를 호출하기 전에 설정되어 있는지 확인합니다. 환경 및 환경 그룹 정보를 참조하세요.
환경이 포함된 환경 그룹의 호스트 이름을 찾습니다.
- 콘솔에서 Google Cloud Apigee > 관리 > 환경으로 이동합니다.
- 환경 그룹 탭을 선택합니다.
- 환경이 포함된 환경 그룹을 찾고 호스트 이름 열에서 값을 복사합니다.
템플릿의 기본 경로를 사용하여 해당 호스트 이름에서 프록시를 호출합니다.
curl https://HOSTNAME/hello
HOSTNAME을 복사한 호스트 이름으로 바꿉니다. 응답이 성공하면 모의 타겟 서비스에서 응답이 전송됩니다.
2부: Gemini용 AI 게이트웨이 빌드
이 섹션에서는 Vertex AI의 Gemini 모델로 요청을 전달하고 비율 제한을 적용하며 API 키를 요구하는 AI 게이트웨이인 더 완전한 프록시를 빌드합니다. 하나의 템플릿, 세 가지 기능, 서비스 계정을 사용합니다.
1부의 간단한 프록시와 달리 이 프록시는 Google Cloud 서비스 (Vertex AI)를 호출합니다. gemini-target 기능은 auth: GoogleAccessToken을 사용하므로 Apigee는 각 Vertex AI 요청에 Google OAuth 토큰을 연결합니다. 이 토큰은 프록시를 배포할 때 만든 후 제공하는
서비스 계정에 대해 발급되므로 이 부분에서는 서비스 계정을 만드는 단계를 추가합니다
(3단계).
1단계: 템플릿 만들기
ai-gateway.yaml이라는 파일을 만듭니다.
gateway: apigee schemaVersion: 1.0.0 name: ai-gateway type: template description: AI gateway that fronts a Gemini model with throttling and API key enforcement. features: - spike-arrest.yaml - verify-api-key.yaml - gemini-target.yaml endpoints: - name: gemini basePath: /v1/gemini routes: - name: default target: gemini
2단계: 기능 만들기
동일한 디렉터리에서 세 가지 기능 파일을 만듭니다.
1부의 spike-arrest.yaml 기능을 재사용합니다.
x-api-key 헤더에 API 키를 요구하도록 verify-api-key.yaml을 만듭니다.
gateway: apigee schemaVersion: 1.0.0 name: verify-api-key displayName: Verify API Key type: feature description: Requires a valid API key in the x-api-key request header. categories: - security defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: VA-VerifyAPIKey policies: - name: VA-VerifyAPIKey type: VerifyAPIKey content: VerifyAPIKey: metadata: name: VA-VerifyAPIKey enabled: "true" continueOnError: "false" DisplayName: VA-VerifyAPIKey APIKey: metadata: ref: request.header.x-api-key
Google 액세스 토큰으로 인증된 Gemini 모델로 라우팅하도록 gemini-target.yaml을 만듭니다.
gateway: apigee schemaVersion: 1.0.0 name: gemini-target displayName: Gemini Target type: feature description: Routes requests to a Gemini model on Vertex AI, authenticated with a Google access token. categories: - llm targets: - name: gemini url: https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent auth: GoogleAccessToken scopes: - https://www.googleapis.com/auth/cloud-platform
PROJECT_ID를 Google Cloud 프로젝트 ID로, REGION를 사용 중인 Vertex AI 리전 (예: us-central1)으로 바꿉니다. 이 기능
은 auth: GoogleAccessToken를 사용하므로 Apigee는 각 Vertex AI 요청에
Google 액세스 토큰을 연결합니다.
모델은 모든 위치에서 사용할 수 없으며 URL은 사용하는 위치에 따라 다릅니다. 앞의 URL은 us-central1의 gemini-2.5-flash와 같이 특정 리전에서 제공되는 모델에 적용되는 리전 형식입니다. 다른 모델은 다른 호스트와 locations/global을 사용하는 전역 엔드포인트에서만 제공됩니다.
url: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL:generateContent
모델이 지원하는 위치를 찾으려면 Vertex AI의 생성형 AI 위치를 참조하세요.
3단계: 프록시의 서비스 계정 만들기
gemini-target 기능은 auth: GoogleAccessToken을 사용하므로 배포된 프록시는 Vertex AI를 서비스 계정 으로 호출합니다. 서비스 계정을 만들고 Vertex AI에 대한 액세스 권한을 부여하며 Apigee 서비스 에이전트가 이를 사용하도록 합니다. 5단계에서 프록시를 배포할 때 이 서비스
계정을 제공합니다. 자세한 내용은
Google
인증
사용을 참조하세요.
- Apigee 조직
과 동일한 Google Cloud 프로젝트에서 사용자 관리 서비스 계정을 만듭니다. (Compute Engine 기본 서비스 계정
은 허용되지 않습니다.) 다른 방법으로 만들려면
서비스 계정 만들기
및 관리를 참조하세요.
gcloud iam service-accounts create SA_NAME \ --project=PROJECT_ID \ --display-name="Apigee AI gateway"이렇게 하면 서비스 계정
SA_NAME@PROJECT_ID.iam.gserviceaccount.com가 생성됩니다. - 서비스 계정에 호출하는 백엔드에 대한 액세스 권한을 부여합니다. Vertex AI
타겟의 경우 Vertex AI 사용자 역할
(
roles/aiplatform.user)을 부여합니다.gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/aiplatform.user"프로젝트의 IAM 정책에 이미 조건부 역할 결합이 포함되어 있는 경우 이 명령어에
--condition=None을 추가합니다. - 서비스 계정에 서비스 계정 토큰 생성자 역할(
roles/iam.serviceAccountTokenCreator)을 부여하여 Apigee 서비스 에이전트가 서비스 계정의 토큰을 생성하도록 합니다.gcloud iam service-accounts add-iam-policy-binding \ SA_NAME@PROJECT_ID.iam.gserviceaccount.com \ --project=PROJECT_ID \ --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"PROJECT_NUMBER를 찾으려면
gcloud projects describe PROJECT_ID --format='value(projectNumber)'를 실행합니다.
4단계: 프록시 가져오기
템플릿을 가져와 API 프록시 버전을 만듭니다.
gcloud beta apigee apis import ai-gateway \
--from-template=ai-gateway.yaml \
--organization=ORG명령어 출력에서 버전 번호를 기록해 둡니다.
5단계에서 필요합니다. 버전 번호만 출력하려면 가져오기 명령어에 --format="value(revision)"을 추가합니다.
5단계: 서비스 계정으로 프록시 배포
AI 게이트웨이 배포는 1부의 간단한 프록시와 두 가지 면에서 다릅니다.
- 3단계에서 만든 서비스 계정을 제공해야 합니다. 서비스 계정 없이 배포하면
배포가
MISSING_SERVICE_ACCOUNT오류와 함께 실패합니다. - 중간 또는 종합 환경에 배포해야 합니다.
이 프록시는 기본 환경에서 지원하지 않는 확장 가능한 정책을 사용합니다. 기본 환경에 배포하면
'확장 가능한 프록시를 기본 환경에 배포할 수 없습니다'
라는 오류가 발생하여 실패합니다. Apigee 환경 유형을 참조하세요.
Apigee UI: 프록시를 배포하고 서비스 계정을 묻는 메시지가 표시되면
입력합니다
SA_NAME@PROJECT_ID.iam.gserviceaccount.com.
단계는
API 프록시 배포를 참조하세요.
배포 API: 서비스 계정을 serviceAccount 쿼리
매개변수로 전달하여
배포
API를 호출합니다. REVISION을
4단계의 버전 번호로 바꿉니다.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST \ "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com"
배포 요청은 즉시 반환됩니다. 배포는 비동기식입니다. 버전의 배포 상태를 폴링합니다. 배포 상태는 READY가 될 때까지 PROGRESSING을 보고합니다.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments"
프록시가 컴파일되면 spike-arrest 및 verify-api-key 기능은 요청 PreFlow에 정책을 추가하고(먼저 비율 제한, 다음으로 API 키 확인) gemini-target 기능은 Vertex AI 백엔드를 추가합니다. 배포가 완료되면 프록시는 서비스 계정으로 Vertex AI를 인증합니다.
6단계: API 키 가져오기
verify-api-key 기능은 유효한 API 키가 없는 요청을 거부하므로 프록시를 호출하기 전에 키가 필요합니다. API 키는 이 프록시가 포함된 API 제품 과 연결된 개발자 앱 의 사용자 인증 정보입니다.
게시
개요
에 설명된 다음 작업을 완료합니다.
- API 제품을 만듭니다. 여기에는
ai-gateway프록시와 배포한 환경이 포함됩니다. - 앱 개발자 를 등록합니다.
- 개발자 앱을 등록합니다. 해당 앱은 해당 API 제품과 연결되어 있습니다.
앱을 등록하면 키가 생성됩니다. 키를 검색하려면 API 키 및 보안 비밀 보기를 참조하세요.
7단계: 프록시 호출
1부 5단계에 설명된 대로 환경 그룹의 호스트 이름을 찾은 후 기본 경로
/v1/gemini에서 프록시를 호출합니다. x-api-key 헤더에 API 키를 전달하고 Gemini
generateContent
요청 본문을 보냅니다.
curl -X POST https://HOSTNAME/v1/gemini \
-H "x-api-key: API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'HOSTNAME을 환경 그룹 호스트 이름으로,
API_KEY을 6단계의 키로 바꿉니다. 응답이 성공하면 모델의 JSON 출력이 반환됩니다. 키를 생략하면 VerifyAPIKey 정책에서 승인 실패가 반환되어 verify-api-key 기능이 적용됨을 확인합니다. 키를 전달하는 다른 방법은
유효한 API 키로 요청 제출을 참조하세요.