IDE와 앱을 로컬 AI 모델로 연결하는 방법 (프라이빗, 온디바이스)

당신의 에디터, 터미널 스크립트, 그리고 지난달에 설치한 AI 도구의 절반은 모두 동일한 프로토콜인 OpenAI HTTP API를 사용합니다. 이 도구들은 모두 해당 프로토콜이 비용을 지불하는 서버를 가리킨다고 가정합니다. 하지만 그럴 필요는 없습니다. Off Grid AI Desktop은 당신의 Mac 또는 PC에 OpenAI 호환 엔드포인트 (endpoint)를 구축해 주는 무료 오픈 소스 앱으로, 이를 통해 해당 도구들이 온디바이스 (on-device) 모델을 대상으로 실행될 수 있습니다.

GitHub ->

무료, 오픈 소스 (AGPL-3.0), 오프라인 실행 가능. 계정 불필요, 텔레메트리 (telemetry) 없음, API 키 불필요.

모든 도구가 사용할 수 있는 주소

기억해야 할 엔드포인트는 하나입니다:

OpenAI 베이스 URL (base URL)을 사용하는 것이라면 무엇이든 이 주소를 사용할 수 있습니다. IDE 확장 프로그램, CLI 도구, Python 스크립트, 브라우저 확장 프로그램, 셸 에일리어스 (shell alias) 등이 모두 해당됩니다. 이 주소와 자리 표시자용 키 (placeholder key)를 제공하기만 하면, 비행기 안에서도 작동하는 프라이빗 추론 백엔드 (inference backend)를 얻을 수 있습니다.

이 주소는 루프백 (loopback)에 바인딩되어 있어 오직 당신의 기기에서만 응답합니다. 네트워크나 인터넷 상의 그 어떤 것도 여기에 접근할 수 없습니다. 그것이 핵심입니다. 당신의 코드, 프롬프트 (prompts), 그리고 파일들은 벤더 (vendor)가 아닌 당신이 제어하는 프로세스로 전달됩니다.

요구 사항

등급	macOS	Windows
최소 사양	Apple Silicon (M1), 16 GB 통합 메모리 (unified memory), macOS 13+, 약 12 GB 여유 디스크	NVIDIA 또는 최신 CPU, 16 GB RAM, Windows 11, 약 12 GB 여유 디스크
권장 사양	M2/M3/M4, 24 GB 이상의 통합 메모리	NVIDIA GPU (CUDA) 또는 Vulkan GPU, 32 GB RAM

Windows에서는 GPU가 없는 경우 CPU 폴백 (fallback)이 작동합니다. 속도는 더 느리지만 실행은 됩니다.

연결 가능한 항목들

이 게이트웨이 (gateway)는 OpenAI-SDK와 호환되므로, 연결할 수 있는 항목의 목록은 매우 깁니다. 개발자들이 가장 먼저 찾는 몇 가지는 다음과 같습니다:

사용자 정의 Base URL (base URL)을 설정할 수 있는 IDE 어시스턴트(assistants) 및 에디터 확장 프로그램(editor extensions). 이들은 채팅 완료(chat completions) 요청을 보내고 로컬 모델이 응답하므로, 코드가 노트북을 절대 벗어나지 않습니다.
터미널에서 빠른 프롬프트(prompts)를 실행하기 위한 curl 한 줄 명령어 또는 셸 함수(shell function).
openai-python 또는 openai-node를 사용하는 스크립트. 두 개의 인자(arguments)만 변경하면 스크립트가 오프라인에서 실행됩니다.
게이트웨이가 두 가지 형태를 모두 노출하므로, 이미 OpenAI 프로토콜을 지원하거나 Ollama 스타일의 모델 배열(models array)을 미러링하는 모든 앱.

하나의 엔드포인트(endpoint)가 텍스트 이상의 기능을 제공합니다. 동일한 OpenAI 경로(routes)를 통해 비전(vision), 임베딩(embeddings), 음성-텍스트 변환(speech-to-text), 텍스트-음성 변환(text-to-speech), 그리고 이미지 생성(image generation) 기능을 사용할 수 있으므로, 이를 대상으로 하는 도구들이 채팅에만 국한되지 않습니다.

스크립트를 연결하기

가장 작은 규모의 테스트부터 시작하세요. 이를 통해 엔드포인트가 응답하는지 확인할 수 있습니다.

curl http://127.0.0.1:7878/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
...

이제 공식 SDK를 사용하여 Python에서 동일하게 실행해 보겠습니다. 중요한 두 줄은 base_url과 api_key입니다.

from openai import OpenAI

client = OpenAI(
...

Node의 경우, openai 패키지를 사용하여 다음과 같이 작성합니다:

import OpenAI from "openai";

const client = new OpenAI({
...

IDE를 연결하기

대부분의 IDE 어시스턴트와 에디터 AI 확장 프로그램은 두 가지 설정, 즉 Base URL과 API 키를 제공합니다. 다음과 같이 설정하세요:

Base URL 또는 API base: http://127.0.0.1:7878/v1
API key: 비어 있지 않은 임의의 문자열 (예: local)
Model: local 또는 GET /v1/models가 보고하는 ID

만약 확장 프로그램에서 프로바이더 유형(provider type)을 묻는다면, OpenAI-compatible(OpenAI 호환) 또는 custom(사용자 정의)을 선택하세요. 설정이 완료되면 확장 프로그램의 채팅, 인라인 완성(inline completion), 편집 기능이 사용자의 디스크에 있는 모델을 대상으로 작동합니다. 어떤 모델이 활성화되어 있는지, 그리고 그 종류(kind: chat, vision, image, speech, transcription)가 무엇인지 확인하려면 다음을 호출하세요:

curl http://127.0.0.1:7878/v1/models

스크립트를 위한 채팅 이상의 기능

동일한 엔드포인트가 모든 모달리티(modality)를 제공하기 때문에, 원래라면 세 개의 서로 다른 벤더(vendors)가 필요했을 작은 도구들을 직접 구축할 수 있습니다.

multipart로 전송하여 whisper.cpp로 오디오 파일 전사(transcribe)하기:

curl http://127.0.0.1:7878/v1/audio/transcriptions \
  -F "file=@meeting.m4a" \
  -F "model=local"

all-MiniLM-L6-v2를 사용하여 로컬 검색 스크립트용 임베딩 (embeddings) 생성하기:

curl http://127.0.0.1:7878/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model": "local", "input": "the cat sat on the mat"}'

또한 /v1/audio/speech에서 텍스트 음성 변환 (text-to-speech)을 지원하며 (Kokoro 사용, WAV 출력, /v1/audio/voices에서 제공하는 voice id 사용), /v1/images/generations에서 이미지 생성 (image generation)을 지원합니다. 베이스 URL(base URL)과 플레이스홀더 키(placeholder key)는 동일합니다.

도구 사용 시 느린 호출 처리하기

일부 호출은 시간이 다소 소요됩니다. 특정 모달리티 (modality)에 대한 첫 번째 요청은 해당 모델을 다운로드하며, 다단계 이미지 생성은 몇 초에서 몇 분 동안 실행됩니다. 스크립트에서 클라이언트 타임아웃 (client timeout)이 발생할 위험을 피하려면 ?async=true, 바디 필드 `

IDE가 127.0.0.1:7878과 통신할 때, 코드는 사용자의 로컬 머신에 있는 프로세스로 전달되어 그곳에서 멈춥니다. 게이트웨이 (gateway)는 추론 (inference)을 위해 외부 호출을 수행하지 않습니다. 텔레메트리 (telemetry)도 없고 계정도 필요하지 않습니다. 앱 전체가 AGPL-3.0 라이선스이므로, 저장소 (repository)를 신뢰하기 전에 앱이 무엇을 하는지 직접 읽어볼 수 있습니다. 네트워크를 차단하더라도 위의 모든 예제는 계속 작동합니다.

시작하기

github.com/off-grid-ai/desktop에서 클론 (clone)하거나 다운로드하세요.
macOS 또는 Windows에서 앱을 설치하고 실행하세요.
게이트웨이가 http://127.0.0.1:7878/v1에서 응답하는지 확인하세요. Scalar 플레이그라운드 (playground)를 보려면 GET /docs를, 명세 (spec)를 보려면 /openapi.json을 브라우징하세요.
각 도구에서 기본 URL (base URL)을 해당 주소로, 키 (key)를 임의의 플레이스홀더 (placeholder)로 설정하세요.
요청을 실행하세요. 각 모달리티 (modality)별로 첫 번째 호출 시 모델을 한 번 다운로드하며, 그 이후에는 모든 것이 오프라인으로 실행됩니다.

향후 계획

로컬 메시 (local mesh)를 통해 다른 페어링된 기기에서 이 게이트웨이에 접속하는 기능입니다. 이를 통해 두 번째 노트북이나 휴대폰이 데스크톱의 모델을 사용할 수 있게 됩니다. 이는 로드맵 (roadmap) 단계이며 아직 출시되지는 않았습니다.
다양한 모달리티에 걸쳐 더 많은 번들 모델 (bundled models)을 제공할 예정입니다.
온디바이스 (on-device) 모델은 Streamable HTTP를 통해 POST /v1/.../mcp 경로의 MCP 도구 (tools)로도 노출되므로, MCP 클라이언트 (clients)가 이를 호출할 수 있습니다. 이에 대해서는 별도의 문서에서 다룹니다.

FAQ

Q: 제 IDE 확장 프로그램 (extension)과 함께 사용할 수 있나요?

확장 프로그램에서 사용자 정의 OpenAI 기본 URL (base URL)과 키 (key)를 설정할 수 있다면 가능합니다. URL을 http://127.0.0.1:7878/v1로, 키를 임의의 플레이스홀더 (placeholder)로 설정하세요.

Q: 정말 무료인가요?

네. AGPL-3.0 오픈 소스이며, 사용량 기반 API (metered API)가 아닙니다. 자신의 하드웨어에서 모델을 실행하므로 토큰 (token) 비용이 발생하지 않습니다.

Q: 오프라인에서도 작동하나요?

네. 각 모달리티 (modality)가 모델을 한 번 다운로드한 후에는 모든 엔드포인트 (endpoint)가 인터넷 연결 없이 작동합니다.

Q: 어떤 클라이언트 (clients)를 지원하나요?

openai-python 및 openai-node를 포함하여 OpenAI HTTP API를 사용하는 모든 것을 지원합니다. 게이트웨이는 또한 해당 형식을 기대하는 도구들을 위해 Ollama 스타일의 모델 배열 (models array)을 미러링 (mirror)합니다.

Q: RAM이 얼마나 필요한가요?

macOS 및 Windows에서는 16 GB로 작동합니다. 더 큰 모델과 이미지 생성 (image generation)을 위해서는 24 GB 이상이 도움이 됩니다. 모델은 한 번에 하나씩 로드되므로, 가장 무거운 단일 작업 (single job)을 기준으로 크기를 결정하세요.

Q: 제 코드는 비공개인가요?

엔드포인트 (endpoint)는 127.0.0.1에 바인딩되어 있으며 외부로의 추론 (inference) 호출을 수행하지 않습니다. 텔레메트리 (telemetry) 없음, 계정 없음, 오픈 소스 (open source)입니다. 귀하의 저장소 (repository)는 귀하의 디스크에 그대로 유지됩니다.

기기 전체에 프라이빗 추론 백엔드 (private inference backend)를 부여하세요.