이 페이지에는 Vertex AI 서비스를 실행할 수 있도록 프로젝트를 준비하기 위해 Google Distributed Cloud (GDC) 오프라인 어플라이언스에서 완료해야 하는 작업이 포함되어 있습니다. 이 페이지에서는 개발 환경에서 gdcloud CLI를 구성하는 방법도 설명합니다. 머신러닝 (ML) 및 인공지능 (AI) 애플리케이션에 Vertex AI를 구현하려는 프로젝트에서 다음 단계를 완료하세요.
구성된 ID 공급자로 인증하고 사용자 ID 및 Kubernetes 클러스터의 kubeconfig 파일을 가져오는 방법에 대한 자세한 내용은 gdcloud CLI 인증을 참고하세요.
서비스 계정 설정
서비스 계정(서비스 ID라고도 함)은 Vertex AI 서비스를 관리하는 데 중요한 역할을 합니다. 워크로드가 Vertex AI 서비스에 액세스하고 승인된 API 호출을 프로그래매틱 방식으로 만드는 데 사용하는 계정입니다. 사용자 계정과 마찬가지로 서비스 계정에는 권한과 역할을 부여하여 안전하고 관리된 환경을 제공할 수 있지만, 실제 사용자와 같이 로그인할 수는 없습니다.
서비스 계정 이름, 프로젝트 ID, 키 쌍의 JSON 파일 이름을 지정하여 Vertex AI 서비스의 서비스 계정을 설정할 수 있습니다.
서비스 계정을 만들고, 역할 바인딩을 할당하고, 키 쌍을 만들고 추가하는 방법을 자세히 알아보려면 프로젝트에서 서비스 계정으로 인증을 참고하세요.
ROLE: 서비스 계정에 할당할 사전 정의된 역할입니다. Role/name 형식으로 역할을 지정합니다. 여기서 Role은 Kubernetes 유형(예: Role 또는 ProjectRole)이고 name은 사전 정의된 역할의 이름입니다. 예를 들어 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)"],[],[],null,["# Set up a project for Vertex AI\n\nThis page contains the tasks you must complete on Google Distributed Cloud (GDC) air-gapped appliance\nto have your project ready to run Vertex AI services. The page\nalso provides instructions on configuring the gdcloud CLI in your\ndevelopment environment. Complete the following steps on the project where you\nwant to implement Vertex AI for your machine learning (ML) and\nartificial intelligence (AI) applications.\n\nIf you lack the necessary permissions, [ask your administrator](#ask-your-administrator)\nto set up the project on your behalf.\n\nAsk an administrator to set up a project for you\n------------------------------------------------\n\nMost tasks to set up a project require administrator access. An administrator\nmust take the following steps to set up a project for you to run\nVertex AI services on the project namespace:\n\n1. [Configure the appliance with the Domain Name System (DNS) information](/distributed-cloud/hosted/docs/latest/appliance/admin/setup#configure-the-appliance).\n2. Determine a meaningful project name and project ID to identify the project.\n3. Set up a project by following the instructions in this document.\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/appliance/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/appliance/platform/pa-user/iam/set-up-role-bindings).\n\nThen, [create a project](/distributed-cloud/hosted/docs/latest/appliance/platform/pa-user/create-a-project) to\ngroup your Vertex AI services together.\n\nInstall the gdcloud CLI\n-----------------------\n\nTo activate GDC air-gapped appliance 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/appliance/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/appliance/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/appliance/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/appliance/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 make authorized\nAPI calls programmatically. 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 [Authenticate with service accounts in projects](/distributed-cloud/hosted/docs/latest/appliance/application/ao-user/iam/service-identity).\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 GDC air-gapped appliance 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 name of the predefined role. For example, the following are roles that you\n can assign to service accounts to use\n [Vertex AI pre-trained APIs](/distributed-cloud/hosted/docs/latest/appliance/application/ao-user/vertex-ai-enable-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`."]]
