Hugging Face Space-ում API բանալին մի դրեք Docker image-ի մեջ

Docker Space-ի API բանալին գրանցեք Space-ի Settings բաժնում որպես Secret։ Եթե այն պետք է աշխատող հավելվածին, կարդացեք միջավայրի փոփոխականից, իսկ եթե անհրաժեշտ է image-ի հավաքման ընթացքում, տրամադրեք միայն համապատասխան RUN քայլի ժամանակավոր mount-ով։ Hugging Face-ի Docker Spaces-ի հրահանգները նկարագրում են գաղտնիքի օգտագործման այս երկու ուղիները։

Նախ պարզեք, թե որ փուլում է պետք բանալին։ Արդեն գործարկված հավելվածից արտաքին API կանչելու համար բավական է runtime Secret-ը։ Build-time mount ավելացրեք միայն այն դեպքում, երբ հավաքման քայլը պետք է ստանա մասնավոր ռեսուրս. այդ քայլից հետո բանալին հավելվածի ֆայլերում պահելու անհրաժեշտություն չկա։

README.md-ում նշեք Docker SDK-ն և պորտը

Նոր Space ստեղծելիս ընտրեք Docker SDK-ն կամ գործող Space-ի README.md ֆայլի սկզբում ավելացրեք YAML բաժին։ Նվազագույն օրինակի տողերը հետևյալ հերթականությամբ են.

1. ---
2. sdk: docker
3. app_port: 7860
4. ---

sdk: docker-ը ընտրում է Docker Space-ը։ app_port: 7860-ը նշում է արտաքինից հասանելի հավելվածի պորտը. հավելվածն ինքը նույնպես պետք է լսի այդ պորտում և ընդունի կոնտեյներից դուրս եկող կապերը։ README.md-ում բանալի մի գրեք. ֆայլը Space-ի պահոցի մաս է, ուստի այն անվտանգ տեղ չէ գաղտնի արժեքի համար։

Հրապարակելուց առաջ համոզվեք, որ հավելվածի մեկնարկի հրամանը համապատասխանում է README-ում նշված պորտին։ Եթե օգտագործում եք այլ պորտ, փոխեք երկու տեղում էլ՝ և՛ հավելվածի կարգավորումներում, և՛ YAML բաժնում։ Պորտի անհամապատասխանությունը կխանգարի հավելվածին հասնելուն, նույնիսկ եթե Docker image-ը հաջողությամբ հավաքվել է։

Variable-ը թողեք բաց տվյալներին, Secret-ը՝ բանալուն

Space-ի Settings բաժնում ոչ գաղտնի մոդելի նույնացուցիչը կարող եք պահել MODEL_REPO_ID անունով Variable-ում, իսկ իրական բանալին՝ API_KEY անունով Secret-ում։ Variable-ի արժեքը նախատեսված է տեսանելի կազմաձևման համար։ Secret-ի արժեքը կարգավորելուց հետո API-ից հետ չի ընթերցվում, թեև բանալու անունը և մետատվյալները հասանելի են կառավարման գործիքներին։

Hugging Face-ի Space-ի կառավարման ուղեցույցը ցույց է տալիս add_space_secret և add_space_variable կանչերը. get_space_secrets-ը վերադարձնում է անունն ու մետատվյալները, իսկ get_space_variables-ը՝ նաև փոփոխականի արժեքը։ Նույն ուղեցույցի համաձայն՝ Docker Space-ը cpu-basic սարքավորման վրա գործարկելու համար անհատական հաշիվը PRO բաժանորդագրության, իսկ կազմակերպությունը Team կամ Enterprise բաժանորդագրության կարիք ունի. վճարովի սարքավորումն ունի վճարման առանձին պայմաններ։ Տեղակայումը պլանավորելիս սա ստուգեք մինչև բանալիներն ավելացնելը։

Secret-ի արժեքը կրկին ստանալու համար հավելվածից կառավարման API կանչելու կարիք չկա. աշխատող Space-ում այն հասանելի է համանուն միջավայրի փոփոխականով։ Եթե արժեքն այլևս չունեք, այն պետք է նորից տրամադրեք կամ փոխարինեք մատակարարի մոտ։ Կարգավորումը փոխելիս հաշվի առեք նաև, որ Space-ի գաղտնիքների փոփոխությունը վերագործարկում է հավելվածը։

Build-ի գաղտնիքը փոխանցեք միայն անհրաժեշտ RUN քայլին

Պայմանական սխալ տարբերակն է Dockerfile-ում գրել ARG API_KEY, ապա ENV API_KEY=$API_KEY։ Այդպես արժեքը կարող է հայտնվել վերջնական image-ի կազմաձևման մեջ։ Գաղտնիք պարունակող ֆայլը COPY հրահանգով ներմուծելն ու հաջորդ քայլում ջնջելը նույնպես անվտանգ լուծում չէ. արդեն ստեղծված շերտը կարող է պահպանել ֆայլը։ Docker-ի build secrets հրահանգները խորհուրդ են տալիս գաղտնիքը տրամադրել RUN քայլի ժամանակավոր mount-ով՝ ARG-ի կամ ENV-ի փոխարեն։

Ահա նվազագույն Dockerfile-ի պայմանական օրինակ։ Այն ենթադրում է, որ նախագծում կա app.py, որը գործարկում է հավելվածը README-ում նշված պորտով, և Settings-ում ստեղծված է BUILD_TOKEN անունով Secret։ Յուրաքանչյուր տարրը Dockerfile-ի առանձին տող է.

1. FROM python:3.11-slim
2. RUN useradd -m -u 1000 user
3. USER user
4. ENV HOME=/home/user
5. WORKDIR /home/user/app
6. COPY --chown=user app.py .
7. RUN --mount=type=secret,id=BUILD_TOKEN,mode=0444,required=true test -s /run/secrets/BUILD_TOKEN
8. CMD ["python", "app.py"]

Օրինակի RUN քայլը միայն ստուգում է, որ գաղտնիքի ֆայլը կա և դատարկ չէ. այն մասնավոր ռեսուրս չի ներբեռնում։ Իրական նախագծում ներբեռնման կամ տեղադրման հրամանը գրեք հենց այդ նույն RUN քայլում և թողեք, որ այն կարդա /run/secrets/BUILD_TOKEN ուղին։ required=true-ն կկանգնեցնի հավաքումը, եթե գաղտնիքը չի տրամադրվել։ Եթե բանալին պետք է միայն գործարկված հավելվածին, RUN տողն ընդհանրապես հեռացրեք։

Տեղային հավաքման ժամանակ նույն գաղտնիքը Docker-ին փոխանցվում է, օրինակ, docker build --secret id=BUILD_TOKEN,env=BUILD_TOKEN . հրամանով՝ նախ միջավայրում սահմանելով BUILD_TOKEN-ը։ Բանալու արժեքը մի գրեք հրամանի տողում։ Mount-ն ինքնին չի պահպանում գաղտնիքը վերջնական image-ում, բայց RUN հրամանը կարող է այն արտածել build log-ում կամ պատճենել ֆայլի մեջ։ Այդ պատճառով արժեքը մի տպեք և ներբեռնված արդյունքի կողքին մի պահեք։

Գործարկման պահին բանալին կարդացեք սերվերային կոդում

Runtime Secret-ը հասանելի է միջավայրի փոփոխականի միջոցով։ Python հավելվածում, օրինակ, os.environ.get("API_KEY")-ը կարդում է Settings-ում ստեղծված համանուն Secret-ը։ Հավելվածի մեկնարկին ստուգեք միայն արժեքի առկայությունը. բացակայության դեպքում ցուցադրեք հասկանալի սխալ՝ առանց բանալին կամ միջավայրի ամբողջ պարունակությունը արտածելու։

Բանալին օգտագործեք այն սերվերային կոդում, որը կատարում է արտաքին API հարցումը։ Մի ներառեք այն դիտարկիչին ուղարկվող JavaScript-ում, HTML պատասխանում կամ հանրային endpoint-ի արդյունքի մեջ։ Space-ի Secret կարգավորումը պաշտպանում է արժեքը պահոցում հրապարակվելուց, սակայն չի կարող կանխել արտահոսքը, եթե հավելվածն ինքն է այն վերադարձնում այցելուին կամ գրում մատյանում։

Ստուգեք UID 1000-ի ֆայլային թույլտվությունները

Docker Space-ի կոնտեյները գործարկվում է UID 1000-ով։ Օրինակում օգտվողը ստեղծվում է մինչև հավելվածի ֆայլը պատճենելը, իսկ COPY --chown=user-ը ֆայլը տալիս է այդ օգտվողին։ Եթե հավելվածը մեկնարկից հետո գրում է մոդելի քեշ, ժամանակավոր ֆայլ կամ ներբեռնված տվյալ, գրելու համար նախատեսված գրացուցակը նույնպես պետք է հասանելի լինի նույն օգտվողին։

Permission denied սխալի դեպքում պարզեք՝ որ ուղին է փորձում գրել հավելվածը։ Այնուհետև տվեք հենց այդ գրացուցակին անհրաժեշտ սեփականատիրությունը կամ ընտրեք օգտվողին հասանելի ուղի։ Build-ի ընթացքում գաղտնիքի mount-ը կարդալու թույլտվությունն ու գործարկման ընթացքում հավելվածի ֆայլերը գրելու թույլտվությունը տարբեր ստուգումներ են. մեկի հաջողությունը մյուսը չի երաշխավորում։

Հրապարակումից հետո ստուգեք արտահոսքի հնարավոր տեղերը

Գործարկված հավելվածը ստուգեք առանց բանալու արժեքը ցուցադրելու։ Հետևյալ հերթականությունը ընդգրկում է պահոցը, image-ը և հավելվածի հրապարակային ելքը.

1. Դիտեք Space-ի պահոցի ֆայլերն ու commit-ների պատմությունը։ Բանալին չպետք է լինի README.md-ում, Dockerfile-ում, app.py-ում կամ հրապարակված .env ֆայլում։ Ընթացիկ ֆայլից արժեքը հեռացնելը չի ջնջում այն հին commit-ից։
2. Վերանայեք Dockerfile-ի ARG, ENV և COPY հրահանգները։ Եթե image-ը հավաքել եք տեղում, դիտեք դրա պատմությունն ու կազմաձևումը՝ համոզվելու, որ այնտեղ գաղտնի արժեք չկա։
3. Դիտեք build և runtime մատյանները, ինչպես նաև հավելվածի հանրային պատասխանները։ Հաստատեք, որ անհրաժեշտ API հարցումն աշխատում է, բայց debug պատասխանում մի արտածեք բանալին կամ միջավայրի բոլոր փոփոխականները։
4. Եթե բանալին հայտնվել է պահոցում, image-ում կամ մատյանում, փոխարինեք այն բանալին տրամադրող ծառայության մոտ և նոր արժեքը գրանցեք Space-ի Secret կարգավորումում։ Միայն հրապարակված ֆայլը խմբագրելը չի վերացնում արդեն բացահայտված բանալու ռիսկը։

Կարդացեք նաև:

• Գաղտնի տվյալը մի՛ տեղադրեք ԱԲ prompt-ում․ պաշտպանեք նաև հիշողությունն ու մատյանները
• Hugging Face թե Replicate․ պարապ GPU-ն կարող է շրջել էժան ընտրությունը
• Gemini 4 Argon-ը դեռ փակ փորձարկման մեջ է․ API-ն սպասելու է