이 페이지에서는 Google Distributed Cloud (GDC) 에어 갭에서 Vertex AI 서비스를 실행하도록 프로젝트를 설정하는 방법을 안내합니다. 여기에는 gdcloud CLI, 신뢰 번들 인증 기관 (CA), 서비스 계정으로 개발 환경을 구성하는 단계가 포함되어 있으므로 애플리케이션과 워크플로에 머신러닝을 통합할 수 있습니다.
이 페이지는 오프라인 애플리케이션과 워크플로를 AI 기능으로 최적화하는 역할을 담당하는 애플리케이션 운영자 그룹 내 애플리케이션 개발자를 위한 페이지입니다. 자세한 내용은 GDC 오프라인 문서 대상을 참고하세요.
관리자에게 프로젝트 설정 요청
프로젝트를 설정하는 대부분의 작업에는 플랫폼 관리자 액세스 권한이 필요합니다. 관리자는 프로젝트를 식별할 수 있는 의미 있는 프로젝트 이름과 프로젝트 ID를 결정해야 합니다. 조직에 속해 있거나 여러 프로젝트를 만들려는 경우 Distributed Cloud에서 인식되는 이름 지정 규칙과 엔티티를 고려하세요. 자세한 내용은 리소스 계층 구조를 참조하세요.
필요한 권한이 없는 경우 관리자에게 대신 프로젝트를 설정해 달라고 요청하세요.
이 문서의 안내에 따라 프로젝트를 설정합니다.
시작하기 전에
프로젝트를 만들고 서비스 계정을 구성하는 데 필요한 권한을 얻으려면 조직 IAM 관리자 또는 프로젝트 IAM 관리자에게 프로젝트 네임스페이스에서 다음 역할을 부여해 달라고 요청하세요.
프로젝트를 만들려면 프로젝트 생성자 (project-creator) 역할을 획득하세요.
서비스 계정을 만들려면 프로젝트 IAM 관리자 (project-iam-admin) 역할을 획득하세요.
구성된 ID 공급자로 인증하고 사용자 ID 및 Kubernetes 클러스터의 kubeconfig 파일을 가져오는 방법에 대한 자세한 내용은 gdcloud CLI 인증을 참고하세요.
서비스 계정 설정
서비스 계정(서비스 ID라고도 함)은 Vertex AI 서비스를 관리하는 데 중요한 역할을 합니다. 워크로드가 Vertex AI 서비스 및 AI 모델에 액세스하고 승인된 API 호출을 프로그래매틱 방식으로 실행하는 데 사용하는 계정입니다. 예를 들어 서비스 계정은 Vertex AI Workbench 노트북을 관리하여 Speech-to-Text API를 사용하여 오디오 파일을 텍스트로 변환할 수 있습니다. 사용자 계정과 마찬가지로 서비스 계정에는 권한과 역할을 부여하여 안전하고 관리된 환경을 제공할 수 있지만, 실제 사용자와 같이 로그인할 수는 없습니다.
서비스 계정 이름, 프로젝트 ID, 키 쌍의 JSON 파일 이름을 지정하여 Vertex AI 서비스의 서비스 계정을 설정할 수 있습니다.
서비스 계정을 만들고, 역할 바인딩을 할당하고, 키 쌍을 만들고 추가하는 방법을 자세히 알아보려면 서비스 계정 관리를 참고하세요.
ROLE: 서비스 계정에 할당할 사전 정의된 역할입니다. Role/name 형식으로 역할을 지정합니다. 여기서 Role은 Kubernetes 유형(예: Role 또는 ProjectRole)이고 name은 사전 정의된 역할의 Kubernetes 리소스 이름입니다. 예를 들어 Vertex AI 사전 학습된 API 중 일부를 사용하기 위해 서비스 계정에 할당할 수 있는 역할은 다음과 같습니다.
AI OCR 개발자 (ai-ocr-developer) 역할을 할당하려면 역할을 Role/ai-ocr-developer로 설정합니다.
AI 음성 개발자 (ai-speech-developer) 역할을 할당하려면 역할을 Role/ai-speech-developer로 설정합니다.
AI Translation Developer (ai-translation-developer) 역할을 할당하려면 역할을 Role/ai-translation-developer로 설정합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThis guide outlines the necessary steps to prepare a project on Google Distributed Cloud (GDC) air-gapped for running Vertex AI services.\u003c/p\u003e\n"],["\u003cp\u003eYou'll need to install the gdcloud CLI to interact with Distributed Cloud services and manage required components.\u003c/p\u003e\n"],["\u003cp\u003eSetting up service accounts is crucial for managing Vertex AI services and allowing your workloads to programmatically access them through authorized API calls.\u003c/p\u003e\n"],["\u003cp\u003eTo complete these tasks, you will likely need the Project Creator (\u003ccode\u003eproject-creator\u003c/code\u003e) and Project IAM Admin (\u003ccode\u003eproject-iam-admin\u003c/code\u003e) roles, otherwise an admin will need to set up the project for you.\u003c/p\u003e\n"],["\u003cp\u003eYou will also need to set up billing for the project on Distributed Cloud to track the costs for your projects.\u003c/p\u003e\n"]]],[],null,["# Set up a project for Vertex AI\n\nThis page guides you through how to set up a project to run Vertex AI services on Google Distributed Cloud (GDC) air-gapped. It includes steps for configuring your development environment with the gdcloud CLI, the trust bundle certificate authority (CA), and your service accounts, so you can begin integrating machine learning into your applications and workflows.\n\nThis page is for application developers within application operator groups who are responsible for optimizing air-gapped applications and workflows with AI features. For more information, see [Audiences for GDC air-gapped documentation](/distributed-cloud/hosted/docs/latest/gdch/resources/audiences).\n\nAsk an administrator to set up a project for you\n------------------------------------------------\n\nMost tasks to set up a project require platform administrator access. An\nadministrator must determine a meaningful project name and project ID to\nidentify the project. If you are part of an organization or plan to create\nmultiple projects, consider what naming conventions and entities are recognized\non Distributed Cloud. For more information, see\n[Resource hierarchy](/distributed-cloud/hosted/docs/latest/gdch/resources/resource-hierarchy).\n\nIf you lack the necessary permissions, ask your administrator to set up the\nproject on your behalf.\n\nSet up a project by following the instructions in this document.\n| **Note:** Certain tasks in Vertex AI require that you use additional Distributed Cloud components besides Vertex AI. For example, online predictions use Distributed Cloud storage buckets to store artifacts such as datasets and models. Also, to track costs for projects, you require a billing account. You might need to perform additional setup tasks and obtain additional roles to use other Distributed Cloud components.\n\nBefore you begin\n----------------\n\nTo get the permissions that you need to create a project and configure service\naccounts, ask your Organization IAM Admin or Project IAM Admin to grant you the\nfollowing roles in your project namespace:\n\n- To create a project, obtain the Project Creator (`project-creator`) role.\n- To create service accounts, obtain the Project IAM Admin (`project-iam-admin`) role.\n\nFor information about these roles, see [Prepare IAM permissions](/distributed-cloud/hosted/docs/latest/gdch/application/ao-user/vertex-ai-ao-permissions).\nTo learn how to grant permissions to a subject, see [Grant and revoke access](/distributed-cloud/hosted/docs/latest/gdch/platform/pa-user/iam/set-up-role-bindings).\n\nThen, [create a project](/distributed-cloud/hosted/docs/latest/gdch/platform/pa-user/create-a-project) to\ngroup your Vertex AI services together.\n[Ensure that billing is enabled for your Distributed Cloud project](/distributed-cloud/hosted/docs/latest/gdch/platform/pa-user/billing/manage-billing-accounts).\n\nInstall the gdcloud CLI\n-----------------------\n\nTo activate Distributed Cloud services and gain access to tools and\ncomponents, install the gdcloud CLI.\n\nFollow these steps to install the gdcloud CLI and manage the required\ncomponents:\n\n1. [Download the gdcloud CLI](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-download).\n2. Initialize the gdcloud CLI:\n\n gdcloud init\n\n For more information, see [Install the gdcloud CLI](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-install).\n3. Install your required components:\n\n gdcloud components install \u003cvar translate=\"no\"\u003eCOMPONENT_ID\u003c/var\u003e\n\n Replace \u003cvar translate=\"no\"\u003eCOMPONENT_ID\u003c/var\u003e with the name of the component you\n want to install.\n\n For more information, see [Manage gdcloud CLI components](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-install#manage-components).\n4. Authenticate with gdcloud CLI:\n\n gdcloud auth login\n\n For more information about how to authenticate with your configured identity\n provider and get a kubeconfig file for your user identity and Kubernetes\n cluster, see [the gdcloud CLI authentication](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-auth).\n\nSet up service accounts\n-----------------------\n\nService accounts, also referred to as service identities, play a crucial role in\nmanaging your Vertex AI services. They are the accounts that your\nworkloads use to access Vertex AI services and AI models and make\nauthorized API calls programmatically. For example, service accounts can manage\nyour Vertex AI Workbench notebook to transcribe audio files using\nthe Speech-to-Text API. Similar to a user account, service accounts can be\ngranted permissions and roles, providing a secure and controlled environment,\nbut they can't sign in like a human user.\n\nYou can set up service accounts for Vertex AI services by\nspecifying the name of your service account, your project ID, and the name of a\nJSON file for key pairs.\n\nTo learn more about how to create a service account, assign role bindings to it,\nand create and add key pairs, see [Manage service accounts](/distributed-cloud/hosted/docs/latest/gdch/application/ao-user/iam/service-identities).\n\nFollow these steps to set up service accounts using the gdcloud CLI:\n\n1. Create a service account:\n\n gdcloud iam service-accounts create \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e: the name of the service account. The name must be unique within the project namespace.\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the project ID where you want to create the service account. If `gdcloud init` is already set, then you can omit the `--project` flag.\n2. Create the application default credentials JSON file and the public and\n private key pairs:\n\n gdcloud iam service-accounts keys create \u003cvar translate=\"no\"\u003eAPPLICATION_DEFAULT_CREDENTIALS_FILENAME\u003c/var\u003e \\\n --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --iam-account=\u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e \\\n --ca-cert-path=\u003cvar translate=\"no\"\u003eCA_CERTIFICATE_PATH\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eAPPLICATION_DEFAULT_CREDENTIALS_FILENAME\u003c/var\u003e: the name of the JSON file, such as `my-service-key.json`.\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the project to create the key for.\n - \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e: the name of the service account to add the key for.\n - \u003cvar translate=\"no\"\u003eCA_CERTIFICATE_PATH\u003c/var\u003e: an optional flag for the path to the certificate authority (CA) certificate that verifies the authentication endpoint. If you don't specify this path, the system CA certificates are used. You must install the CA in the system CA certificates.\n\n Distributed Cloud adds the public key to the service account keys you\n use to verify the JSON web tokens (JWT) that the private key signs. The\n private key is written to the application default credentials JSON file.\n3. Grant the service account access to project resources by assigning a role\n binding. The name of the role depends on the Vertex AI service\n you want to use the service account for.\n\n gdcloud iam service-accounts add-iam-policy-binding \\\n --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --iam-account=\u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e \\\n --role=\u003cvar translate=\"no\"\u003eROLE\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the project to create the role binding in.\n - \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e: the name of the service account to use.\n - \u003cvar translate=\"no\"\u003eROLE\u003c/var\u003e: the predefined role to assign to the\n service account. Specify roles in the format `Role/name` where *Role* is\n the Kubernetes type, such as `Role` or `ProjectRole`, and *name* is the\n Kubernetes resource name of the predefined role. For example, the\n following are roles that you can assign to service accounts to use some of\n the Vertex AI pre-trained APIs:\n\n - To assign the AI OCR Developer (`ai-ocr-developer`) role, set the role to `Role/ai-ocr-developer`.\n - To assign the AI Speech Developer (`ai-speech-developer`) role, set the role to `Role/ai-speech-developer`.\n - To assign the AI Translation Developer (`ai-translation-developer`) role, set the role to `Role/ai-translation-developer`.\n\n | **Note:** To learn more about predefined roles and the names you must assign depending on the Vertex AI service or model you want to use, see [Prepare IAM permissions](/distributed-cloud/hosted/docs/latest/gdch/application/ao-user/vertex-ai-ao-permissions)."]]
