이 페이지는 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인 엔드포인트 클라이언트는 이 경로에서 프록시를 호출합니다. 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)으로 바꿉니다. 이 기능은 Apigee가 Vertex AI에 대한 각 요청에 Google 액세스 토큰을 연결하도록 auth: GoogleAccessToken를 사용합니다.
모델은 모든 위치에서 사용할 수 있는 것은 아니며 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오류가 발생하여 배포가 실패합니다. - 중간 또는 종합 환경에 배포해야 합니다.
이 프록시는 Base 환경에서 지원하지 않는 확장 가능한 정책을 사용합니다. 따라서 이 프록시를 Base 환경에 배포하면
확장 가능한 프록시를 기본 환경에 배포할 수 없습니다
라는 오류가 발생합니다. 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 제품과 연결된 개발자 앱의 사용자 인증 정보입니다. 게시 개요에 설명된 다음 작업을 완료합니다.
ai-gateway프록시와 이를 배포한 환경이 포함된 API 제품을 만듭니다.- 앱 개발자 등록
- 해당 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 키로 요청 제출을 참고하세요.