FreeToken 로컬 API: MoE 서빙 설정 가이드

FreeToken 로컬 API는 호스팅된 모델 엔드포인트에 의존하는 대신 FreeToken을 로컬 추론 서비스로 사용하는 것을 의미합니다. FreeToken은 소비자용 하드웨어에서 프런티어급 오픈 웨이트 모델을 실행하도록 설계된 엣지 네이티브 Mixture-of-Experts 서빙 엔진입니다. 문서화된 아키텍처는 GPU 메모리, CPU 리소스, 호스트 메모리 및 사용 가능한 인터커넥트를 하나의 추론 플랫폼으로 결합합니다.

실질적인 장점은 유연성입니다. MoE 모델은 수천억 개의 파라미터를 포함하면서도 각 토큰마다 더 적은 수의 전문가만 활성화할 수 있습니다. FreeToken은 모든 모델 가중치가 항상 GPU 메모리에 남아 있어야 한다고 가정하는 대신, 이러한 전문가를 효율적으로 이동하고 캐시하는 데 중점을 둡니다.

영상 주요 내용:

• FreeToken은 개인 하드웨어에서 대규모 MoE 모델을 로컬로 서빙하는 것을 목표로 합니다.
• 엔진은 라우팅을 인식하는 전문가 캐싱과 CPU–GPU 협업을 강조합니다.
• 보고된 벤치마크는 독립적으로 재현될 때까지 프로젝트 자체 벤치마크로 간주해야 합니다.
• 하드웨어 호환성은 기존의 멀티 백엔드 런타임보다 여전히 제한적입니다.

공식 FreeToken GitHub 저장소는 이 프로젝트를 Apache License 2.0 소프트웨어로 명시합니다. 또한 Windows와 Linux용 데스크톱 애플리케이션 및 uv 또는 pip를 통한 CLI 설치 방법을 제공합니다. 따라서 이 프로젝트는 로컬 실험, 연구 및 에이전트 워크플로에 적합하지만, 사용자는 추론 엔진과 보장된 HTTP API를 구분해야 합니다.

가장 깔끔한 설정 방법은 그래픽 워크플로를 원하는지, 반복 가능한 개발 환경을 원하는지에 따라 달라집니다. 저장소는 데스크톱 앱 경로와 CLI 경로를 모두 문서화합니다. 현재 프로젝트 정보에서 macOS 지원 빌드는 지원 환경으로 명시되어 있지 않으며, 현재 초점은 Windows와 Linux입니다.

설치하기 전에 운영 체제, NVIDIA 또는 기타 지원되는 가속기 구성, 시스템 메모리 및 모델 형식을 확인하세요. 다른 런타임에서 지원되는 모델이 FreeToken에서도 수정 없이 작동할 것이라고 가정하지 마세요.

저장소는 소스 설치 경로도 제공합니다.

git clone <repository-url>
cd FreeToken
uv venv
source .venv/bin/activate
uv pip install -e ".[accel]"

이 워크플로를 적용할 때는 공식 문서에서 안내하는 정확한 저장소 URL과 플랫폼별 활성화 명령을 사용하세요. 제공된 소스 내용만으로는 범용 HTTP 서버 명령이 확립되어 있지 않으므로, 검증되지 않은 엔드포인트를 프로덕션 스크립트에 삽입하지 마세요.

FreeToken이 성공적으로 실행되면 로컬 API 워크플로를 단계적으로 구축하세요. 먼저 직접 생성을 검증하고, 다음으로 반복 가능한 모델 로딩을 확인하세요. 그 후에야 에이전트, 편집기 또는 사용자 지정 클라이언트를 연결해야 합니다. 이러한 순서는 모델 문제와 통합 문제를 분리해 줍니다.

로컬 서비스는 코딩 에이전트에 유용할 수 있습니다. 요청이 사용자의 하드웨어에 남아 호스팅 제공업체의 속도 제한이나 모델 서비스 종료 일정의 영향을 받지 않기 때문입니다. 그렇더라도 메모리, 지연 시간, 컨텍스트 크기 및 프로세스 안정성을 모니터링해야 합니다.

다음 워크플로를 사용하세요.

• 짧은 프롬프트와 적당한 컨텍스트로 시작합니다.
• 선택한 모델이 여러 요청에 걸쳐 일관되게 응답하는지 확인합니다.
• 처음부터 가장 큰 프롬프트로 테스트하지 말고 컨텍스트 길이를 점진적으로 늘립니다.
• GPU 메모리, 호스트 메모리 및 시스템 응답성을 관찰합니다.
• 단일 턴 추론이 안정된 후에만 도구 호출이나 에이전트 루프를 추가합니다.
• 더 작은 모델 또는 축소된 컨텍스트를 위한 대체 구성을 유지합니다.

FreeToken의 시맨틱 인식 캐싱은 도구 호출과 사고 블록을 포함한 에이전트 컨텍스트 편집을 위해 설계되었습니다. 세션이 구조적인 방식으로 변경될 때 불필요한 컨텍스트 재계산을 피하는 것이 의도된 이점입니다. 실제 캐시 동작은 모델, 컨텍스트 패턴, 사용 가능한 메모리 및 런타임 구성에 따라 달라집니다.

성능을 테스트할 때는 초당 토큰 수 이상의 항목을 측정하세요. 다음을 기록합니다.

• 첫 토큰까지 걸리는 시간
• 생성 시작 후 디코딩 처리량
• 단일 턴의 최악 지연 시간
• 프리필 중 메모리 사용량
• 디코딩 중 메모리 사용량
• 클라이언트 또는 감시 프로세스가 느린 요청을 종료하는지 여부

빠른 평균값은 허용할 수 없는 후반부 지연을 숨길 수 있습니다. 에이전트의 경우 가끔 타임아웃을 초과하는 요청은 느리더라도 안정적으로 완료되는 구성보다 유용성이 떨어질 수 있습니다.

FreeToken의 차별화된 설계는 서로 다른 하드웨어가 탄력적인 추론 플랫폼처럼 작동하도록 만드는 데 있습니다. 저장소에는 대역폭 적응형 CPU–GPU 공동 실행, 더블 버퍼링 프리필 스트리밍, 전역 LRU 전문가 캐싱, 그래프 호환 실행 및 FTW 고속 가중치 형식이 명시되어 있습니다.

가장 중요한 개념은 전문가 배치입니다. MoE 모델에서는 선택된 전문가만 각 토큰의 계산에 참여하지만, 라우팅이 변경될 때 사용 가능한 전문가에 계속 접근할 수 있어야 합니다. 캐시는 자주 선택되는 전문가의 반복 전송을 줄일 수 있으며, CPU–GPU 실행은 특정 머신에서 사용 가능한 대역폭에 맞춰 조정될 수 있습니다.

하드웨어 선택은 이미 보유한 장비에서 시작해야 합니다. 현재 프로젝트 자료에서 가장 명확한 대상은 충분한 호스트 메모리를 갖춘 최신 NVIDIA 시스템입니다. 이 엔진은 모든 운영 체제와 가속기에서 성숙한 런타임을 대체하는 범용 솔루션이 아닙니다.

FreeToken을 다른 로컬 런타임과 비교할 때는 테스트 조건을 공정하게 유지하세요.

• 동일한 모델 가중치와 비교 가능한 양자화를 사용합니다.
• 프롬프트 길이, 출력 제한 및 샘플링 설정을 동일하게 유지합니다.
• 프리필 속도와 디코딩 속도를 분리합니다.
• 중앙값 지연 시간과 최악 지연 시간을 모두 기록합니다.
• 캐시를 예열한 후 테스트를 반복합니다.
• 정확한 소프트웨어 및 드라이버 버전을 기록합니다.

현재 확인 가능한 벤치마크 논의에서는 일부 MoE 워크로드에서 프로젝트 측의 강력한 결과를 보고하지만, 검토 당시 독립적인 벤치마크는 아직 이용 가능하지 않았다는 점도 강조합니다. 이러한 수치는 보편적인 보장이 아니라 유용한 방향성 자료로 간주하세요.

첫 실행 문제는 대부분 네 가지 영역 중 하나에서 발생합니다. 지원되지 않는 하드웨어, 불완전한 가속기 설치, 적합하지 않은 모델 파일 또는 문서화되지 않은 엔드포인트를 전제로 하는 통합입니다. 이 순서대로 해결하세요.

설치에 실패하면 공식 저장소의 지침으로 돌아가 환경을 확인하세요. 애플리케이션은 실행되지만 생성에 실패한다면 여러 변수를 동시에 변경하기 전에 더 작거나 알려진 지원 모델을 테스트하세요. 생성은 작동하지만 클라이언트가 연결되지 않는다면 URL 경로, 포트 또는 요청 스키마를 추측하지 말고 최신 서빙 문서를 확인하세요.

설정을 신뢰할 수 있는 상태로 간주하기 전에 다음 릴리스 체크리스트를 사용하세요.

• 2026년의 현재 버전과 설치 날짜를 확인합니다.
• 공식 저장소 URL과 릴리스 노트를 저장합니다.
• 콜드 스타트와 캐시가 예열된 요청을 테스트합니다.
• 일반 응답 시간과 최악 응답 시간을 모두 측정합니다.
• 프로세스가 예상되는 가장 긴 프롬프트를 처리하고 유지되는지 확인합니다.
• 더 작은 대체 모델을 준비해 둡니다.
• 인증 및 전송 보호 기능이 문서화되어 있지 않다면 신뢰할 수 있는 네트워크 외부에 로컬 서비스를 노출하지 마세요.