Obsidian의 저장소 구조를 AI 에이전트의 작업 디렉터리로 매핑하는 Claudian 플러그인은 파일 시스템 접근, 셸 명령 실행, 의미 기반 검색을 실시간으로 처리하는 확장 프레임워크이다. 이 아키텍처는 기본 제공 모델 외에 자체 학습된 머신러닝 모델 또는 도메인 특화 파인튜닝 모델을 유연하게 연결할 수 있는 인터페이스를 제공한다.
플러그인 아키텍처 및 지원 범위
Claudian은 단순한 대화 창을 넘어 컨텍스트 인식형 협업 엔진으로 동작한다. Cloud Code, Codex, OpenCode 등 주요 AI 백엔드를 기본으로 지원하며, 플러그인 레이어를 통해 사용자의 Vault를 샌드박스 환경에서 실행 가능한 컨텍스트로 변환한다.
커스텀 모델 연결을 위한 3가지 구현 경로
1. 환경 변수 기반 모델 별칭 등록
런타임 초기화 단계에서 환경 변수를 파싱하여 커스텀 모델 식별자를 레지스트리에 주입할 수 있다. CUSTOM_MODEL_REGISTRY 키를 설정하면 UI 선택기에 항목이 동적으로 바인딩된다.
// 설정 파싱 모듈 예시
const REGISTRY_ENV_KEY = "CLAUDIAN_CUSTOM_MODELS";
const rawConfig = process.env[REGISTRY_ENV_KEY] || "";
export function parseModelAliases(input: string): string[] {
return input
.split(",")
.map(alias => alias.trim())
.filter(alias => /^[a-z0-9\-_\.]+$/i.test(alias));
}
// 터미널 실행: export CLAUDIAN_CUSTOM_MODELS="llama3-finetuned,qwen7b-local"2. MCP(Model Context Protocol) 기반 외부 서비스 연동
MCP는 Claudian과 외부 모델 서버 간 통신을 표준화하는 핵심 레이어이다. 지연 초기화(Lazy Loading) 패턴을 적용하여 @mention 구문이 감지될 때만 서버 인스턴스를 활성화함으로써 메모리 점유율을 최적화한다.
// .claudian/mcp_registry.json
{
"endpoints": {
"local_inference_engine": {
"uri": "http://127.0.0.1:8080/api/v1/generate",
"activateOnDemand": true,
"scope": ["read_files", "semantic_search"]
}
}
}3. 독자적인 제공자(Provider) 모듈 개발
고급 사용자는 확장 포인트를 활용해 신규 AI 런타임을 구현할 수 있다. IAiAgentRuntime 인터페이스를 준수하는 클래스를 작성한 후 확장 허브에 등록하면 프레임워크가 자동으로 연결 관리와 오류 처리를 담당한다.
import { IAiAgentRuntime, StreamPayload, TokenCallback } from "@claudian/core";
export class CustomLlmAdapter implements IAiAgentRuntime {
async streamResponse(payload: StreamPayload, callback: TokenCallback): Promise<void> {
// 외부 API 호출 및 스트리밍 데이터 파싱 로직 구현
}
async getContextWindowSpec(): Promise<{ maxInput: number; maxOutput: number }> {
return { maxInput: 32000, maxOutput: 4096 };
}
}
// 확장 허브에 런타임 등록
ExtensionHub.mount("custom-llm-runtime", new CustomLlmAdapter());리소스 할당 및 실행 파라미터 튜닝
컨텍스트 윈도우 동적 관리
모델별 토큰 제한은 런타임 시점에 동적으로 계산된다. 기본 할당량은 20만 토큰이며, 대용량 모델 호출 시 contextThresholds 맵을 수정하여 100만 토큰까지 확장하거나 특정 모델에 하드 리미트를 강제할 수 있다.
추론 깊이 매핑
각 모델의 연산 리소스 할당 정책은 열거형 상수로 매핑되어 자동 조정된다. 경량 모델은 중간 단계 추론을 기본으로 실행하며, 고급 모델은 심층 분석 모드로 전환된다. 지원하지 않는 파라미터는 내부적으로 안전한 기본값으로 폴백된다.
enum InferenceDepth {
SHALLOW = 1,
BALANCED = 2,
DEEP = 3,
MAXIMUM = 4
}
function resolveDepth(modelFamily: string): InferenceDepth {
if (modelFamily.includes("lightweight")) return InferenceDepth.BALANCED;
if (modelFamily.includes("reasoning")) return InferenceDepth.MAXIMUM;
return InferenceDepth.DEEP;
}실무 적용 시나리오
- 로컬 LLM 파이프라인 구축: Ollama 또는 vLLM으로 실행 중인 오픈소스 모델을 MCP 엔드포인트로 연결하고, 파일 I/O 및 코드 검색 도구 권한을 할당하여 프라이빗 개발 보조 도구로 활용.
- 도메인 특화 모델 연동: 의료 문헌 분석, 정적 코드 품질 검사, 통계 시각화 생성 등 특정 작업에 최적화된 파인튜닝 모델을 전용 실행 슬롯에 배치.
- 다중 에이전트 라우팅: 세션 내에서 태스크 복잡도에 따라 모델을 동적으로 교체. 단순 구문 변환은 저비용 모델에, 논리적 추론은 고사양 모델에 위임하여 비용 대비 처리 효율 극대화.
시스템 성능 최적화 기법
- 메모리 효율화: 필수 컨텍스트만 로드하는 필터링 로직 적용, 동일 프롬프트 해시 기반 결과 캐싱, 병렬 태스크 실행을 통한 처리량 증대.
- 응답 지연 단축: 백그라운드 워밍업 프로세스 유지, 유사한 요청의 일괄 전송(Batching), 네트워크 대기 시간 절약을 위한 프록시 캐싱 설정.
운영 모니터링 및 디버깅
실행 상태는 토큰 소모량, 평균 응답 시간, 호출 실패 비율 등 주요 지표를 통해 추적된다. 문제 발생 시 세션 히스토리 로그, 토큰 스트림 디코딩 내역, 단계별 실행 타임라인 분석 도구를 활용해 병목 현상을 정확히 진단할 수 있다.
보안 및 운영 가이드라인
- 구성 관리: 점진적 모델 추가 및 권한 최소화 원칙 적용. 정기적인 리소스 사용량 감사 수행.
- 보안 격리: 샌드박스 환경에서 외부 모델 실행, 모든 입력 데이터에 대한 유효성 검사 검증, 중요 출력물에 대한 수동 검토 워크플로우 도입.
- 유지보수: 설정 파일 버전 관리 시스템 연동, 세션 데이터 정기 백업, 플러그인 및 모델 버전 업사이클링 일정 수립.
Claudian의 확장 아키텍처를 활용하면 Obsidian 환경을 맞춤형 AI 개발 및 연구 허브로 전환할 수 있다. 환경 변수 주입, MCP 프로토콜 표준화, 맞춤형 런타임 구현을 조합하여 프로젝트 요구사항에 최적화된 지능형 작업 흐름을 설계할 수 있다.