소개

단 30분 만에 무제한 연습 문제를 생성하고 실시간 지능형 채점을 제공하는 스페인어 AI 비서가 성공적으로 출시되었습니다. 백엔드는 값비싼 중앙 클라우드에서 구동되는 것이 아니라, 새롭게 부상하는 분산형 AI 컴퓨팅 네트워크인 Gonka에 전적으로 의존합니다. 전체 실습 기록, 핵심 코드, 그리고 온라인 데모는 다음과 같습니다.

분산형 AI 컴퓨팅을 위한 새로운 패러다임

Gonka 는 검증된 하드웨어 공급업체 간의 OpenAI 유사 추론 작업에 대한 부하 분산을 구현하여 새로운 분산형 AI 서비스 생태계를 구축하는 작업증명 기반 AI 컴퓨팅 네트워크입니다. Gonka 네트워크는 GNK 토큰을 결제 인센티브로 사용하고 무작위 검사를 통해 사기를 효과적으로 방지합니다. 개발자는 OpenAI API 호출 방법을 이해하면 Gonka 네트워크와 신속하게 통합하여 애플리케이션을 배포할 수 있습니다.

실제 사례 연구: 지능형 스페인어 학습 애플리케이션

개인화된 연습 문제를 지속적으로 생성하는 스페인어 학습 앱을 만들어 보겠습니다. 다음과 같은 사용 사례를 상상해 보세요.

• 사용자가 "새로운 연습 시작"을 클릭하면 AI가 빈칸 하나를 포함하는 빈칸 채우기 문장을 생성합니다.
• 사용자가 답을 입력하고 '확인'을 클릭하면 AI가 즉시 점수와 개인 맞춤형 분석을 제공합니다.
• 시스템은 자동으로 다음 연습으로 넘어가서 몰입형 학습 주기를 만듭니다.

온라인 데모: carrera.gonka.ai

기술 아키텍처 분석

이 애플리케이션은 고전적인 프런트엔드와 백엔드 분리 아키텍처를 채택합니다.

• React 프런트엔드: Vite 기반으로 구축되었으며 OpenAI 인터페이스 표준과 완벽하게 호환됩니다.
• 노드 프록시 계층: 요청 서명 및 전달을 담당하는 핵심 코드는 50줄에 불과합니다.

기존 OpenAI 통합과의 유일한 차이점은 주요 보안을 보장하는 서버 측 서명 단계가 추가되었다는 것입니다. 다른 모든 작업은 표준 OpenAI 채팅 완료 호출과 일관성을 유지합니다.

빠른 시작 가이드

환경 요구 사항: Node.js 20+

저장소를 복제합니다

git 클론 git@github.com:product-science/carrera.git

cd 카레라

Gonka 계정을 만들고 환경 변수를 설정하세요

# 추론된 CLI를 사용하여 계정 생성

# CLI 정보는 빠른 시작 가이드를 참조하세요. 다운로드 방법:

# https://gonka.ai/developer/quickstart/#2-계정-생성

# ACCOUNT_NAME은 계정 키 쌍에 대한 읽기 가능한 식별자 역할을 하는 로컬로 고유한 이름이 될 수 있습니다.

계정 이름="카레라-퀵스타트"

NODE_URL=http://node2.gonka.ai:8000

추론된 create-client "$ACCOUNT_NAME" \

--노드 주소 "$NODE_URL"

# 개인 키 내보내기(서버에서만 사용 가능)

GONKA_PRIVATE_KEY=$(추론된 키 내보내기 "$ACCOUNT_NAME" --unarmored-hex --unsafe)를 내보냅니다.

프록시 서비스 시작

cd 곤카-프록시

npm 설치 및 npm 실행 빌드

NODE_URL=http://node2.gonka.ai:8000 ALLOWED_ORIGINS=http://localhost:5173 PORT=8080 npm 시작

건강 검진

컬 http://localhost:8080/healthz

# 예상 반환 값: {"ok":true,"ready":true}

프런트엔드 애플리케이션 실행

CD 웹

npm 설치

VITE_DEFAULT_API_BASE_URL=http://localhost:8080/v1 npm에서 개발을 실행합니다.

애플리케이션에서 "설정"을 열고 기본 URL이 미리 입력되어 있는지 확인하세요. 모델을 선택하세요(예: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8; https://node1.gonka.ai:8443/api/v1/models에서 현재 사용 가능한 모델 목록을 확인할 수 있습니다). "연결 테스트"를 클릭하세요.

핵심기술 구현

Gonka 프록시 서비스는 Gonka와의 통합에 핵심적인 역할을 합니다. 프록시 서비스는 키를 사용하여 요청에 서명한 다음 네트워크를 통해 OpenAI와 유사한 호출을 전달합니다. 개발자는 애플리케이션에 이러한 프록시를 배포하면 Gonka에서 추론 작업을 처리할 수 있습니다. 실제로는 권한이 있는 사용자만 추론을 요청할 수 있도록 인증 메커니즘을 추가하는 것이 좋습니다.

프록시 서비스에서 사용하는 환경 변수:

// gonka-proxy/src/env.ts

const env를 내보냅니다 = {

포트: num("포트", 8080),

GONKA_PRIVATE_KEY: str("GONKA_PRIVATE_KEY"),

NODE_URL: str("NODE_URL"),

허용된 출처: (process.env.ALLOWED_ORIGINS ?? "*")

.나뉘다(",")

.map((s) => s.trim())

.filter(부울),

};

Gonka OpenAI TypeScript SDK(gonka-openai)를 사용하여 클라이언트를 생성하세요 (Go 및 Python 버전도 사용 가능하며, 더 많은 언어에 대한 지원이 지속적으로 업데이트되고 있습니다. 코드 저장소를 팔로우하세요):

// gonka-proxy/src/gonka.ts

"gonka-openai"에서 import { GonkaOpenAI,solveEndpoints };

"./env"에서 { env }를 가져옵니다.

비동기 함수 createGonkaClient()를 내보냅니다.

const 엔드포인트 = resolveEndpoints({ sourceUrl: env.NODE_URL })를 기다립니다.

새로운 GonkaOpenAI({gonkaPrivateKey: env.GONKA_PRIVATE_KEY, 엔드포인트})를 반환합니다.

}

OpenAI 호환 채팅 완료 엔드포인트(/v1/chat/completions)를 공개합니다.

// gonka-proxy/src/server.ts

app.get("/healthz", (_req, res) => res.json({ ok: true, ready }));

앱.post("/v1/chat/completions", 비동기(요청, 응답) => {

`!ready` 또는 `!client`가 발견되면 `res.status(503).json({ error: { message: "프록시가 준비되지 않았습니다" } });`를 반환합니다.

const body = req.body는 ChatCompletionRequest입니다.

if (!body || !body.model || !Array.isArray(body.messages)) {

return res.status(400).json({ error: { message: "model과 messages 매개변수를 모두 제공해야 합니다." } });

}

노력하다 {

const streamRequested = Boolean(body.stream);

const { stream: _ignored, ...rest } = 본문;

if (!streamRequested) {

const 응답 = client.chat.completions.create({ ...rest, stream: false })를 기다립니다.

res.status(200).json(응답)을 반환합니다.

}

// …

server.ts 파일에는 스트리밍 서비스(SSE)에 대한 패스스루 지원도 포함되어 있으며, 개발자는 스트리밍을 지원하는 클라이언트에서 `stream: true`를 설정하여 SSE를 활성화할 수 있습니다. Gonka는 재현 가능한 빌드와 손쉬운 배포를 보장하기 위해 Dockerfile 도 제공합니다.

# gonka-proxy/Dockerfile

# ---- 빌드 단계 ----

노드:20-알파인 AS 빌드에서

작업 디렉토리 /앱

package*.json tsconfig.json ./을 복사합니다.

src ./src를 복사하세요

npm ci && npm run build를 실행합니다.

# ---- 작업 단계 ----

노드에서:20-알파인

작업 디렉토리 /앱

ENV NODE_ENV=생산

복사 --from=build /app/package*.json ./

npm ci --omit=dev를 실행하세요

복사 --from=build /app/dist ./dist

엑스포즈 8080

CMD ["노드", "dist/server.js"]

기술 분석: 프런트엔드(공급업체에 구애받지 않는 디자인)

React 앱은 OpenAI와 호환되므로 Gonka의 구체적인 구현 세부 사항을 알 필요가 없습니다. 단순히 OpenAI와 유사한 엔드포인트를 호출하고 앞서 언급한 연습 루프 인터페이스를 렌더링하기만 합니다.

모든 백엔드 상호작용은 web/src/llmClient.ts에서 처리되며, 이는 채팅 완료 엔드포인트에 대한 단일 호출을 수행합니다.

// 웹/src/llmClient.ts

const url = `${s.baseUrl.replace(/\/+$/, "")}/채팅/완료`;

const 헤더: Record<string, string> = { "Content-Type": "application/json" };

if (s.apiKey) headers.Authorization = `Bearer ${s.apiKey}`; // 선택적 매개변수

const res = await fetch(url, {

방법: "POST"

헤더,

본문: JSON.stringify({ 모델: s.model, 메시지, 온도 }),

신호,

});

if (!res.ok) {

const body = res.text().catch(() => "");를 기다립니다.

LLM 오류 ${res.status}: ${body}`라는 새로운 오류를 발생시킵니다.

}

const 데이터 = res.json();

const 텍스트 = 데이터?.선택?.[0]?.메시지?.내용 ?? "";

{텍스트, 원시: 데이터}를 반환합니다.

API 서비스 제공자를 지정하려면 상단의 "설정" 팝업에서 기본 URL을 설정하세요. 여기에서 모델도 설정할 수 있으며, 기본값은 Qwen/Qwen3-235B-A22B-Instruct-2507-FP8입니다. 오프라인 환경에서 로컬 테스트를 수행하려면 기본 URL을 mock:으로 설정하고, 실제 호출의 경우 개발자의 프록시 주소(빠른 시작 섹션에 미리 입력됨)로 설정하세요.

// 웹/src/settings.ts

내보내기 함수 getDefaultSettings(): 설정 {

const prodBase = (import.meta as any).env?.VITE_DEFAULT_API_BASE_URL || "";

const baseUrlDefault = prodBase || "모의:";

{ baseUrl: baseUrlDefault, apiKey: "", 모델: "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8" }를 반환합니다.

}

앱 프롬프트 및 평가 메커니즘

우리는 두 가지 프롬프트 템플릿을 사용합니다:

생성기 프롬프트: "당신은 스페인어 교사입니다... 엄격한 JSON 형식으로만 출력하세요... 정답, 지침, 난이도를 포함하여 정확히 하나의 빈칸(____)을 포함하는 빈칸 채우기 테스트 문장을 생성하세요."

채점 지침: "당신은 스페인어 교사로서 과제를 채점하고 있습니다... 합격/불합격 여부와 구문 분석 지침을 포함하여 엄격한 JSON 형식으로 출력합니다."

빌드 프로세스에 대한 예제 코드 조각:

// 웹/src/App.tsx

const sys: 채팅메시지 = {

역할: "시스템",

내용: 당신은 상호작용적인 연습문제를 디자인하는 스페인어 교사입니다.

엄격한 JSON 형식으로만 출력합니다(설명 텍스트나 코드 마크업 없음). 객체에는 다음 키가 포함되어야 합니다.

{

"type": "cloze",

"text": "<____로 표시된 공백이 딱 하나만 포함된 스페인어 문장>",

"answer": "<빈칸에 있는 유일한 정답>",

"지침": "<명확한 지침>",

"난이도": "초보자|중급|고급"

}

콘텐츠 가이드라인:

- 자연스러운 생활 장면을 활용하세요

- 빈칸을 하나만 남겨두세요(문장에서 ____ 표시를 정확히 사용하세요)

- 문장은 8~20단어 사이로 유지하세요.

- 문장은 스페인어로만 작성되었습니다. 설명은 영어로 작성될 수 있습니다.

- 다양한 연습에 중점을 둡니다: se/estar, 과거형과 반과거형, 가정법, por/para, 일관성, 일반적인 전치사, 핵심 어휘.

};

모델이 출력 형식을 이해할 수 있도록 몇 가지 간단한 예시를 추가한 후, JSON을 파싱하여 연습 문제를 렌더링했습니다. 채점 과정에서도 엄격한 JSON 형식을 사용하여 합격/불합격 결과와 간략한 설명을 출력합니다.

구문 분석 메커니즘은 내결함성이 뛰어납니다. 필요할 때 자동으로 코드 마커를 정리하고 첫 번째 JSON 데이터 블록을 추출합니다.

// 웹/src/App.tsx

// 설명 텍스트나 코드 마크업을 포함할 수 있는 모델 출력을 조정하는 장애 허용 JSON 추출기입니다.

함수 extractJsonObject<TExpected>(raw: string): TExpected {

const trimmed = String(raw ?? "").trim();

const 펜스 = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);

const 후보 = 펜스 ? 펜스[1] : 트리밍됨;

const tryParse = (s: 문자열) => {

노력하다 {

JSON.parse(s)를 TExpected로 반환합니다.

} 잡다 {

정의되지 않은 값을 반환합니다.

}

};

const 직접 = tryParse(후보);

if (직접) 직접 반환;

const 시작 = 후보.indexOf("{");

const 끝 = 후보.마지막 인덱스("}");

if (시작 !== -1 && 끝 !== -1 && 끝 > 시작) {

const 블록 = 후보.슬라이스(시작, 끝 + 1);

const 구문 분석 = tryParse(블록);

(구문분석)이면 구문분석을 반환합니다.

}

모델 응답에서 JSON을 구문 분석할 수 없습니다.라는 새로운 오류가 발생합니다.

}

개발자를 위한 후속 제안:

• 사용자 정의 운동 유형 및 채점 규칙 추가

• 스트리밍 UI 활성화(에이전트는 이미 SSE를 지원함)

• Gonka 브로커에 인증 및 속도 제한 추가

• 웹 애플리케이션을 빌드할 때 개발자 인프라에 에이전트를 배포하고 VITE_DEFAULT_API_BASE_URL을 설정합니다.

요약 및 전망

왜 곤카를 선택해야 하나요?

1. 비용상의 이점: 기존 클라우드 서비스에 비해 분산 컴퓨팅은 추론 비용을 크게 줄여줍니다.
2. 개인정보 보호: 요청은 프록시를 통해 서명되며, 키는 결코 노출되지 않습니다.
3. 호환성: OpenAI 생태계와 완벽하게 호환되며 마이그레이션 비용이 매우 낮습니다.
4. 신뢰성: 분산 네트워크는 높은 서비스 가용성을 보장합니다.

Gonka는 AI 개발자에게 분산 컴퓨팅 시대로의 원활한 전환을 지원합니다. 본 문서에 설명된 통합 방법을 통해 개발자는 기존 개발 방식을 유지하면서 분산 네트워크의 비용적 이점과 기술적 이점을 누릴 수 있습니다. 분산 AI 인프라가 지속적으로 개선됨에 따라, 이 개발 모델은 차세대 AI 애플리케이션의 표준 관행이 될 것으로 예상됩니다. 동시에 Gonka는 더욱 실용적인 기능을 출시하고 개발자와 함께 지능형 교육 애플리케이션, 콘텐츠 생성 플랫폼, 개인 맞춤형 추천 시스템, 자동화된 고객 서비스 솔루션 등을 포함한 다양한 AI 애플리케이션 시나리오를 탐색할 것입니다.

원본 링크: https://what-is-gonka.hashnode.dev/build-a-production-ready-ai-app-on-gonka-end-to-end-guide

Gonka.ai 소개

Gonka는 효율적인 AI 컴퓨팅 파워를 제공하도록 설계된 탈중앙화 네트워크로, 글로벌 GPU 컴퓨팅 파워를 최대한 활용하여 의미 있는 AI 워크로드를 수행합니다. 중앙화된 게이트키퍼를 제거함으로써 Gonka는 개발자와 연구자에게 컴퓨팅 리소스에 대한 허가 없는 접근을 제공하는 동시에, 모든 참여자에게 자체 토큰인 GNK를 통해 보상을 제공합니다.

Gonka는 미국 AI 개발사 Product Science Inc.에서 인큐베이팅되었습니다. 웹 2 업계 베테랑이자 Snap Inc.의 전 핵심 제품 디렉터였던 Libermans 형제가 설립한 이 회사는 2023년에 1,800만 달러의 투자를 성공적으로 유치했습니다. 투자자로는 OpenAI 투자자 Coatue Management, Solana 투자자 Slow Ventures, K5, 그리고 Insight와 Benchmark의 파트너들이 포함되었습니다. 이 프로젝트의 초기 참여자로는 6blocks, Hard Yaka, Gcore, Bitfury 등 웹 2-웹 3 분야를 선도하는 기업들이 있습니다.

공식 웹사이트 | Github | X | Discord | 백서 | 경제 모델 | 사용자 매뉴얼