Octop 딥다이브
— AI 비서 여러 명을 하나의 서비스로 묶는 법

1프로젝트 한줄 요약

Octop은 한 서버에서 여러 사용자의 AI 비서를 관리하고, 웹·메신저·CLI·예약 작업을 연결하는 자체 호스팅 플랫폼입니다. 사용자는 비서마다 모델, 성격, 도구, 지식베이스를 설정할 수 있고, 팀 기능에서는 진행자 역할의 비서가 다른 전문가에게 일을 나눠 줍니다.

이 저장소에서 배울 핵심은 모델을 만드는 방법보다, 모델을 사용하는 여러 사람과 여러 작업의 경계를 설계하는 방법입니다. 로그인한 사람은 누구인지, 어느 비서의 대화인지, 어느 기록을 읽어도 되는지, 응답 도중 브라우저가 닫히면 무엇을 보관해야 하는지가 실제 제품의 문제입니다.

사용자가 보내는 한 문장의 여행

1. 대시보드가 비서별 WebSocket에 연결하고 사용자 토큰을 보냅니다.
2. 서버가 비서 접근 권한, 대화 식별자, 선택한 도구와 스킬을 확인합니다.
3. 화면 입력을 공통 InboundMessage로 바꿔 채널 처리기에 넣습니다.
4. GlobalProcessor가 실행 요청을 조립하고 에이전트의 응답 조각을 처리합니다.
5. 응답은 화면으로 흘러가고, 대화 기록·도구 실행 정보·사용량은 각 저장 경로로 이어집니다.

코드의 출발점은 src/octop/launch.py:run_foreground()입니다. 이 함수가 OctopServer.start(), build_app(), uvicorn을 연결합니다. pyproject.toml의 CLI 진입점은 octop.cli.main:cli입니다.

2왜 주목받는가

2026-10-23 GitHub 기준 스타 10,787개, 포크 1,382개이며 GitHub Trending Monthly #17에 선정됐습니다. 생성일은 2026-07-08, 최신 릴리스는 2026-10-18의 v1.0.2입니다. 순위와 별 개수만으로 사용자가 왜 관심을 보였는지까지 입증할 수는 없습니다. 다음은 README의 지향점과 실제 구현을 바탕으로 읽을 수 있는 매력입니다.

2-1. 여러 입구가 같은 비서와 기록으로 연결됩니다

README는 웹, CLI, Feishu·Telegram·Discord 등 여러 메신저와 예약 작업을 한 제품으로 묶는다고 설명합니다. 실제로 src/octop/infra/server.py:_boot_runtime()는 AgentManager, Gateway, CronManager를 같은 서비스 묶음으로 조립합니다. 입구마다 계정과 모델 설정을 다시 만드는 부담을 줄이는 방향입니다.

Octop의 강점은 기능 하나의 새로움보다, 대화·권한·도구·저장을 하나의 사용 흐름으로 연결하는 데 있습니다. 예를 들어 문서 검색이 가능한 비서를 메신저에 연결하려면 문서 접근 권한도 함께 이어져야 합니다. 기능 목록 사이에 숨은 연결 비용을 공부할 수 있다는 점이 교육 자료로서도 중요합니다.

2-2. 경쟁 제품을 볼 때 비교할 축

다음 표는 특정 제품의 최신 기능 점수표가 아닙니다. 일반 대화 서비스, 에이전트 개발 도구, 자체 호스팅 플랫폼 중 무엇을 고르는지 판단하는 비교입니다. Octop 열은 커밋 dd9dce4에서 확인한 구성입니다.

실제 대안과 연결해서 보기

Open WebUI도 검색·도구 확장을 제공하므로 단순한 기능 유무로 우열을 정하기 어렵습니다. Open WebUI 공식 기능 문서와 LangGraph 공식 개요 문서를 기준으로 비교하고, Octop의 장점은 코드에 구현된 운영 흐름의 결합으로 읽는 편이 정확합니다. LangGraph는 대체 개발 경로인 동시에 Octop 실행 엔진의 간접 의존성이기도 합니다.

2-3. 작은 배포에서 시작할 수 있는 구조

기본 제어 데이터베이스는 SQLite이고, 별도 메시지 브로커는 필수 구성요소가 아닙니다. src/octop/infra/gateway/gateway.py:boot()에서 ChannelManager와 처리기를 프로세스 안에 조립합니다. 이는 설치할 서비스 수를 줄이지만, 다중 서버 고가용성을 자동으로 제공한다는 뜻은 아닙니다.

2-4. 기능의 존재와 완성도를 구분하세요

README는 AgentTeams를 베타로 표시하고 모바일 클라이언트를 비공개 시험 단계로 설명합니다. 코드에 팀·원격 Android 관련 모듈이 있다는 사실만으로 모든 플랫폼의 안정성을 보증할 수는 없습니다. 관심 요인에 대한 설명은 기능 구성에서 얻은 해석이며, 트렌딩 유입 원인에 대한 실측 결과는 아닙니다.

3기술 스택 전체 지도

pyproject.toml의 >=는 최소 버전 조건이고, uv.lock은 의존성을 해결해 기록한 버전입니다. 같은 원리로 프런트엔드는 dashboard/package.json과 dashboard/package-lock.json을 함께 읽어야 합니다. 아래의 잠금 버전은 잠금 파일에 기록된 값이며 실제 설치 버전과 다를 수 있습니다.

3-1. 백엔드: Python 서비스와 외부 실행 패키지

표의 경로는 저장소 루트 기준입니다. CLI에는 click>=8.1, 터미널 표현에는 rich>=13.7, 암호 처리에는 argon2-cffi>=23.1과 pyjwt>=2.8이 선언돼 있습니다. PostgreSQL 연결은 psycopg[binary]>=3.2를 사용합니다.

3-2. 프런트엔드: 대화 화면을 넘어선 관리 콘솔

@xterm/xterm 5.5.0은 터미널 UI, react-virtuoso ^4.18.10은 긴 목록을 다루는 선택지, react-markdown ^10.1.0은 Markdown 표현용 의존성입니다. dashboard/src/api/request.ts는 토큰 저장, 갱신 헤더 반영, 초기 설정이 끝나지 않았을 때의 처리를 모읍니다.

dashboard/vite.config.ts의 빌드 결과 경로는 src/octop/dashboard입니다. Python wheel에 정적 UI를 포함하므로 배포된 서버가 API와 화면을 함께 제공할 수 있습니다. 이 결과물 디렉터리와 실제 UI 소스인 dashboard/src를 구별하세요.

3-3. 인프라·빌드·데스크톱

저장소의 주 언어만 보면 놓치는 제품 설계가 프런트엔드와 패키징 코드에 들어 있습니다. 데스크톱 앱은 Electron이나 Tauri로 구현된 것으로 추정하면 안 됩니다. desktop/README.md는 Wails 셸이 포함된 실행 환경을 풀고 Octop 프로세스를 시작한다고 설명합니다.

품질 검사도 구분해서 읽어야 합니다. .github/workflows/ci.yml에는 Linux·Windows의 Python 3.12 작업과 별도의 실제 자격증명 테스트 작업이 있습니다. Makefile의 all은 포맷·린트·타입·Python 테스트를 묶지만, 이름만 보고 프런트엔드 Vitest까지 모두 실행한다고 단정할 수는 없습니다.

4아키텍처 심화 분석

4-1. 먼저 전체 시스템을 한 장으로 보기

이 그림은 책임의 지도입니다. 모든 CLI 명령이 HTTP를 통과하지는 않습니다. src/octop/cli/support/에는 저장소를 직접 다루는 경로와 짧게 서버를 띄워 실행 기능을 사용하는 경로가 나뉘어 있습니다. 요청 입구가 달라도 같은 데이터와 도메인 규칙을 사용하도록 구성한 것입니다.

4-2. 패턴 ① 조립 지점과 의존성 주입

src/octop/launch.py:run_foreground()가 바깥쪽 조립 지점입니다. src/octop/infra/server.py:OctopServer.start()는 경로와 설정을 준비하고, DB를 연 뒤 run_migrations()와 build_shared_services()를 호출합니다. 최초 설정에서 DB 선택이 미뤄진 경우에는 서비스를 모두 만들기 전에 반환하는 분기도 있습니다.

src/octop/infra/db/services.py의 RepoBundle.from_pool()은 사용자·비서·대화 저장소에 같은 DatabasePool을 전달합니다. SharedServices는 경로·설정·저장소 묶음을 보관합니다. HTTP 계층은 src/octop/api/deps.py:get_server()로 조립된 서버를 받아 사용합니다.

비서 수명에는 중복 시작 문제도 있습니다. src/octop/infra/agents/manager.py:_start_agent()는 비서별 수명 잠금을 잡고 기존 등록을 확인한 뒤 acreate_agent()로 생성합니다. 이미 있으면 기존 비서를 반환하며, 모델 설정이 없으면 상태를 failed로 남깁니다. 시작 요청이 겹쳤을 때 같은 비서를 두 번 만들지 않으려는 멱등성 설계를 읽을 수 있습니다.

# src/octop/infra/db/services.py의 조립 관계를 줄인 개념 예시
db = 선택한_데이터베이스
repos = RepoBundle.from_pool(db)
services = SharedServices(paths=paths, config=config, repos=repos)
# 각 기능은 설정 파일 대신 필요한 서비스·저장소를 전달받는다.

FastAPI의 공식 의존성 문서가 설명하는 “필요한 값을 대신 준비해 전달한다”는 개념을 실제 제품의 서비스 조립까지 확장해 볼 수 있습니다. 다만 컨테이너 하나에 모든 기능을 넣으면 결합이 커질 수 있으므로, 각 클래스가 받는 인자 중 무엇이 정말 필요한지 같이 살펴보세요.

4-3. 패턴 ② 입력 어댑터와 공통 메시지 파이프라인

웹 대화 입구는 src/octop/api/routers/chat/ws.py:dashboard_chat_ws()입니다. 토큰을 해석하고 assert_agent_access()로 비서 접근을 확인한 뒤, UserTurnWsFrame.model_validate()로 프레임 형태를 검사합니다. 유효한 로그인과 특정 비서를 사용할 권한은 서로 다른 단계입니다.

src/octop/api/routers/chat/turn.py:prepare_dashboard_turn()는 선택한 MCP·스킬을 검사하고 사용자와 비서에 맞는 대화를 찾습니다. 이어서 build_dashboard_inbound()가 화면 전용 데이터를 공통 메시지로 바꿉니다. 아래는 그 함수의 핵심 필드를 발췌한 것입니다.

return InboundMessage(
    channel_id=WS_CHANNEL_ID,
    channel_type=ThreadRegistry.CHANNEL_DASHBOARD,
    tenant_id=agent_id,
    channel_subject=ChannelSubject(subject_id=str(user_id)),
    channel_session_id=prepared.session_key,
    content=list(prepared.inbound_content),
    metadata=metadata,
)

tenant_id라는 이름이 여기서는 비서 식별자를 담는다는 점이 중요합니다. 이 필드를 사용자 식별자로 혼동하면 메시지 경로를 잘못 읽게 됩니다. 실제 사용자 식별자는 주체 정보와 메타데이터 등 별도 문맥으로 전달됩니다.

dashboard_chat_ws()는 channel_manager.enqueue(WS_CHANNEL_ID, inbound)를 호출합니다. src/octop/infra/gateway/process/processor.py의 GlobalProcessor는 __call__()과 iter_turn_chunks()에서 공통 입력을 처리합니다. 웹용 스트림에서는 AgentManager.stream()의 결과를 승인 정책·기록·사용량 처리와 연결합니다.

입구의 형식을 공통 메시지로 바꾸면 실행 로직을 공유할 수 있지만, 사용자와 대화의 권한 정보도 끝까지 함께 전달해야 합니다. subscribe와 cancel 처리에서도 서버가 row.agent_id와 row.user_id를 검사하는 이유가 여기에 있습니다.

연결 종료는 작업 취소와 다릅니다. dashboard_chat_ws()의 정리 코드는 허브에서 연결을 해제하지만 진행 중인 대화를 취소하지 않습니다. 소스 주석도 이를 제한적인 스트림 재연결로 설명합니다. 다시 구독하면 이후 조각을 받을 수 있습니다. 팀 대화에는 subscribe_with_member_catchup()을 통해 메모리에 남은 구성원 응답 텍스트를 다시 보내는 경로도 있지만, 모든 누락 이벤트의 완전한 재전송을 보장하지는 않습니다.

4-4. 패턴 ③ 저장소 인터페이스와 상태의 분리

src/octop/infra/db/pool.py에는 공통 DatabasePool 프로토콜과 SqlitePool, PostgresPool이 있습니다. 저장소는 공통 연결·트랜잭션 형태를 사용하고, 마이그레이션은 SQLite·PostgreSQL 파일 쌍으로 관리합니다. src/octop/infra/db/migrate.py:_discover()가 DB 종류에 맞는 SQL을 고릅니다.

# SqlitePool에서 실제 사용하는 설정과 트랜잭션 순서
PRAGMA foreign_keys = ON
PRAGMA journal_mode = WAL

BEGIN IMMEDIATE
# 읽기·쓰기 작업 수행
COMMIT
# 예외 경로에서는 ROLLBACK

SQLite 연결 하나는 threading.RLock으로 보호합니다. BEGIN IMMEDIATE는 읽은 뒤 쓰기로 전환하는 사이에 다른 연결이 먼저 변경하는 상황을 줄이려는 선택입니다. WAL이 쓰기 작업을 무제한 병렬화한다는 뜻은 아닙니다. SQLite 공식 WAL 문서도 동시 작성자는 하나라는 제약을 설명합니다.

인터페이스가 같아도 두 DB가 완전히 같아지는 것은 아닙니다. qmark_to_pyformat()는 ?를 %s로 단순 치환하며, 함수 설명에는 문자열 리터럴을 구분하지 않는다고 명시돼 있습니다. 추상화가 해결한 범위와 남겨 둔 제약을 함께 읽는 연습이 됩니다.

src/octop/infra/server.py:_boot_runtime()는 버전형 기록을 만들 때 PostgreSQL이면 ValueError를 발생시킵니다. 따라서 “PostgreSQL 지원”은 모든 부속 저장소와 기능이 PostgreSQL로 옮겨진다는 약속이 아닙니다.

작은 RAG 구현이 보여 주는 성능의 경계

src/octop/infra/knowledge/chunk.py:chunk_text()는 기본 800문자 창에 120문자를 겹쳐 자릅니다. src/octop/infra/knowledge/jobs.py:process_document()가 파싱·분할·임베딩·색인 교체를 잇고, enqueue_index_document()는 실행기 스레드로 동기 작업을 넘깁니다. 파싱·OCR 메모리를 고려한 INDEX_CONCURRENCY의 기본값은 1입니다.

src/octop/infra/knowledge/index.py:KnowledgeIndex.search()는 전체 청크를 읽어 Python에서 코사인 유사도를 계산하고 정렬합니다. 청크 수를 N, 벡터 차원을 D라고 하면 코드 구조상 거리 계산은 대략 O(ND), 정렬은 O(N log N)입니다. 이는 구현을 읽고 얻은 복잡도 해석이며 실측 처리량은 아닙니다. 전용 벡터 DB나 근사 검색을 사용하는 코드는 아닙니다.

src/octop/infra/knowledge/retrieve.py:retrieve_context()는 기본 상위 8개와 6,000문자 예산을 사용합니다. 이 예산에는 각 조각 앞의 출처 문구와 본문이 포함됩니다. 전체 머리말·구분자·끝의 인용 메타데이터는 별도로 붙으므로 최종 문자열 전체의 엄밀한 6,000문자 상한으로 해석하지 마세요. 검색 실패 시 경고를 남기고 빈 문맥을 반환하는 경로도 있어, 답변이 왔다고 검색 성공이 보장되지는 않습니다.

4-5. 패턴 ④ 진행자와 구성원을 나눈 비동기 조정

src/octop/infra/agents/manager.py:_apply_team_host_config()는 일반 비서에 peer_invoke_mode="sync", 팀 진행자에 "async"를 적용하는 분기를 둡니다. 진행자에게는 구성원 목록을 전달하고 MCP 설정·스킬 디렉터리·추가 도구를 제한합니다. 진행자가 직접 모든 도구를 쓰기보다 업무를 조정하는 방향입니다.

src/octop/infra/agents/teams/team_manager.py:TeamManager는 팀 대화방 연결을 맡습니다. install_host_dispatch()가 stream_peer_to_room()과 stream_host_followup_to_room()을 연결하고, record_peer_turn()는 구성원 기록을 남긴 뒤 fan_in_peer_turn()으로 이어집니다.

compose_followup()은 구성원 결과를 진행자 후속 입력으로 만들며 결과 발췌 상한은 _FOLLOWUP_RESULT_MAX_CHARS = 6000입니다. 전체 구성원 기록을 진행자 입력에 무한히 복사하지 않는 선택입니다. 대화방에 보이는 기록과 진행자의 모델 입력이 같은 자료구조일 필요는 없습니다.

5디렉토리 구조 해부

src/octop/infra/desktop/은 호스트 화면을 제어하는 기능이고, desktop/src/은 앱 창을 띄우는 Go 클라이언트입니다. 폴더 이름만으로 같은 기능이라고 묶지 마세요. 프런트엔드 빌드 산출물은 src/octop/dashboard/로 향합니다.

5-1. 실제 줄 수로 보는 공부 범위

커밋 dd9dce4 기준의 물리적 줄 수입니다. 빈 줄·주석을 포함하며 마지막 줄에 줄바꿈이 없어도 한 줄로 셉니다. Python 핵심은 src/octop/에서 /library/와 /plugins/bundled/에 속한 파일을 분리한 값입니다. TypeScript는 dashboard/src/만 대상으로 .test. 파일명을 구분했습니다.

Python 전체는 약 26.5만 줄, 대시보드 TypeScript·TSX는 약 19.8만 줄입니다. 이 숫자는 위에 명시한 범위의 합계이며 문서·JSON·잠금 파일은 포함하지 않습니다. 파일 수는 테스트 사례 수가 아니고, 줄 수는 품질이나 난이도의 점수도 아닙니다.

5-2. 초보자를 위한 읽기 순서

1. src/octop/config.py와 src/octop/launch.py에서 실행의 입구를 찾습니다.
2. src/octop/api/routers/chat/turn.py에서 입력이 어떤 자료구조가 되는지 봅니다.
3. src/octop/infra/gateway/process/processor.py에서 비서 실행까지 연결합니다.
4. src/octop/infra/knowledge/chunk.py처럼 작은 순수 함수로 내려가 손으로 결과를 계산합니다.
5. 같은 기능의 테스트를 읽고 정상·오류·경계 조건을 역으로 정리합니다.

6학습 포인트 (기술별)

파일을 얼마나 많이 읽었는지보다, 입력 하나가 변할 때 결과가 왜 달라지는지 설명할 수 있는지가 학습의 기준입니다. 다음 기술은 작은 예제로 따로 익힌 뒤 해당 파일로 돌아오면 이해가 쉬워집니다.

위 표의 파일 경로는 저장소 루트 기준입니다.

6-1. 비동기라고 해서 모든 작업이 동시에 빨라지지는 않습니다

enqueue_index_document()는 asyncio.create_task()로 작업을 만들고, 세마포어 안에서 run_in_executor()를 호출합니다. 실행기는 동기 파싱·임베딩이 이벤트 루프를 계속 점유하지 않게 하고, 세마포어는 동시에 파싱하는 문서 수를 제한합니다. 두 장치의 목적이 다릅니다.

6-2. 스트리밍 상태는 페이지 수명보다 길 수 있습니다

dashboard/src/pages/Chat/hooks/useChat.ts는 useSyncExternalStore(subscribeStore, getStoreSnapshot)로 대화 상태를 구독합니다. dashboard/src/pages/Chat/hooks/chatStore.ts:notify()는 새 스냅숏 참조를 만들고 구독자에게 알립니다. UI 컴포넌트가 직접 모든 응답을 소유하는 것보다 화면 이동과 스트림 수명을 분리하기 쉽습니다.

// dashboard/src/pages/Chat/hooks/useChat.ts의 구독 관계를 줄인 예시
const subscribeStore = (cb: () => void) =>
  chatStore.subscribe(stableSessionId, cb);
const getStoreSnapshot = () => chatStore.getSnapshot(stableSessionId);
const state = useSyncExternalStore(subscribeStore, getStoreSnapshot);

React 공식 문서는 이 훅을 React 밖의 저장소를 구독하는 API로 설명합니다. 새 스냅숏을 언제 만드는지, 구독 해제는 누가 하는지, 대화 식별자가 바뀌면 무엇을 다시 구독하는지 확인하세요.

6-3. 인증·권한·암호화를 한 단어로 묶지 않기

src/octop/infra/users/password.py는 Argon2id 해시와 암호 정책을 담당합니다. src/octop/infra/auth/tokens.py:sign_token()는 HS256 JWT에 sub·uname·role·iat·exp를 넣습니다. JWT 서명은 위변조 확인 수단이며 토큰 내용의 비밀 보관을 뜻하지 않습니다.

src/octop/api/common/agent.py:assert_agent_owner()는 소유자 또는 관리자 여부를, assert_agent_access_row()는 공유 비서 접근까지 고려합니다. “볼 수 있다”와 “설정을 바꿀 수 있다”가 다른 권한이라는 점을 배우기 좋습니다. 확인할 테스트는 tests/integration/test_boundary_authz.py입니다.

6-4. 테스트를 기능의 질문 목록으로 읽기

tests/unit/knowledge/test_chunk.py는 공백 입력과 잘못된 겹침을, tests/unit/knowledge/test_index.py는 유사도 정렬·문서 교체·삭제를 확인합니다. tests/integration/test_chat_ws.py는 더 넓은 통신 경계를 살펴볼 출발점입니다. 작은 순수 함수에서 시작해 저장과 통신 경계로 넓히는 순서가 좋습니다.

7하드웨어 / 시스템 요구사항

README의 공식 안내는 macOS·Linux·Windows, 현대적인 멀티코어 CPU, 프로세스와 모델·임베딩 캐시를 위한 수 GB RAM, DB·작업공간·문서를 위한 디스크입니다. 동시 사용자 수별 최소 사양이나 처리량 표는 제시하지 않습니다. 아래 숫자는 소규모 학습 환경을 잡기 위한 추정 출발점이며 공식 보증 사양이 아닙니다.

Octop 서버의 메모리 요구량과 로컬 LLM의 메모리 요구량을 더해 생각해야, 자체 호스팅의 실제 비용이 보입니다. 원격 모델을 쓰면 서버에 대화 모델 가중치를 올릴 필요가 줄지만 API 호출 비용과 외부 전송은 남습니다.

단순 계산으로 70억 매개변수의 4비트 가중치는 약 3.5GB입니다. 여기에 양자화 메타데이터, 실행 버퍼, 대화 캐시가 추가되므로 이것을 필요 VRAM으로 그대로 쓰면 안 됩니다. Octop이 7B 모델을 기본 내장한다는 뜻도 아닙니다.

7-1. 실제 설정에서 먼저 확인할 값

출처는 src/octop/config.py:OctopConfig입니다. Docker 구성은 OCTOP_BIND_HOST=0.0.0.0으로 바꾸고 포트를 게시하므로 노출 범위가 다릅니다. docker/docker-compose.yml은 기본 호스트 데이터 경로를 ~/.octop, 컨테이너 내부 경로를 /data/.octop으로 연결합니다.

# config.json에서 시간대와 문서 UI를 명시하는 예시
{
  "default_timezone": "Asia/Seoul",
  "enable_api_docs": true
}

docker/Dockerfile의 Node 힙 상한 기본값은 2048MB이며 미리 예약하는 메모리나 전체 빌드 사용량이 아닙니다. Docker 빌드는 build:docker로 Vite만 실행하고 전체 tsc 검사를 건너뜁니다. 이미지 빌드 성공을 타입 검사 성공으로 간주하지 마세요.

7-2. 선택 기능은 별도 설치·권한이 필요합니다

pyproject.toml의 local-embedding은 fastembed·huggingface_hub, knowledge-ocr은 RapidOCR·ONNX Runtime·PyMuPDF를 추가합니다. Playwright 패키지 설치와 Chromium 바이너리 준비도 별개입니다. 데스크톱 빌드는 Go 1.25 이상과 Wails 도구가 필요하며, desktop/README.md는 Linux의 GTK4·WebKitGTK 6, macOS 12 이상을 안내합니다.

8직접 해볼 수 있는 실습 과제

다음 과제는 저장소를 읽고 손으로 추적하거나 별도의 작은 예제를 만드는 방식으로 시작할 수 있습니다. 원격 모델 키나 실제 메신저 계정은 필요하지 않습니다. 실습의 완성 조건을 먼저 정하면, 거대한 저장소에서도 배운 내용을 작은 결과물로 남길 수 있습니다.

size = 4
overlap = 1
step = size - overlap  # 3
# 시작 위치 0, 3, 6
# 결과: ["abcd", "defg", "ghij"]

cos(q, v) = dot(q, v) / (norm(q) * norm(v))
A: 1.0
B: 0.0
C: 약 0.9701
# k=2이면 A, C 순서

9관련 기술 심화 학습 로드맵

Python 함수·리스트·딕셔너리와 기본 HTML을 아는 독자를 가정합니다. 아직 익숙하지 않다면 1주 차를 늘려도 좋습니다. 매주 한 장의 설명이나 작은 예제를 완성하고, 그 결과를 실제 소스와 대조하세요.

표의 파일 경로는 저장소 루트 기준입니다.

학습 순서는 라이브러리 이름을 외우는 순서가 아니라, 데이터의 형태에서 시작해 상태의 수명과 실패의 경계로 넓혀 가는 순서입니다. 모델 응답이 좋은지 나쁜지와 별개로 검사할 수 있는 동작부터 익히면 디버깅도 쉬워집니다.

9-1. 관심 분야별 다음 갈림길

• 백엔드: 입력 검증 → 자원별 권한 → 트랜잭션 → 마이그레이션의 호환성을 더 공부하세요.
• 프런트엔드: 스트림 이벤트 → 외부 저장소 → 긴 대화 렌더링 → 네트워크 재연결 순으로 확장하세요.
• AI 응용: 청크 분할 → 임베딩 → 검색 평가 → 근거 인용 → 도구 승인으로 이어 가세요.
• 플랫폼: 단일 프로세스 수명 → 지속 데이터 → 백업·복구 → 다중 인스턴스 조정으로 넓혀 가세요.

10핵심 키워드 사전

특히 Thread, 체크포인트, 대화방, 작업공간은 서로 다른 수명과 책임을 가집니다. 이름을 외운 뒤에는 각각 “누구 소유인가, 어디에 저장되는가, 언제 없어지는가”를 붙여 설명해 보세요.

11참고 링크

11-1. 저장소와 제품 문서

• Octop 공식 저장소 — 프로젝트와 현재 개발 흐름.
• v1.0.2 릴리스 — 2026-10-18 배포 버전.
• 분석 기준 README — 제품 지향점과 기능 상태.
• API 설명 — 자원별 HTTP 경로.
• 전문가 팀 설계 문서 — 대화방·배정·취소의 제약.
• 커넥터 문서 — 외부 서비스와 연결 방식.
• 데스크톱 패키징 문서 — Wails와 묶음 실행 환경.

11-2. 이 글의 핵심 코드로 바로 가기

• Python 의존성 선언 · Python 잠금 버전.
• UI 의존성 선언 · UI 잠금 버전.
• 프로세스 조립 · 서비스 수명.
• 웹 대화 입구 · 공통 입력 변환.
• GlobalProcessor · 비서 수명·설정 변환.
• DB 추상화와 트랜잭션 · 로컬 벡터 검색.
• 팀 대화방 조정 · CI 검사 구성.

11-3. 관련 기술의 공식 자료

• FastAPI 의존성 주입 — 요청 처리와 필요한 서비스 연결.
• Python 3.12 asyncio — 작업·실행기·동기화의 기초.
• SQLite WAL — 동시성과 체크포인트의 실제 제약.
• React 외부 저장소 구독 — 구독 함수와 스냅숏의 계약.
• uv 공식 문서 — Python 의존성과 잠금 파일.
• MCP 공식 문서 — 도구 연결 프로토콜의 배경.
• Wails v3 공식 문서 — Go 데스크톱 앱의 구성.
• Octop Harness · Octop Gateway · Octop Memory — 별도 런타임의 구현 경계.

현재 상태 (2026-10-23 확인)

11-4. README와 실제 소스 사이에서 기억할 차이

• README의 공통 처리기 이름은 HarnessProcessor지만 실제 조립 클래스는 GlobalProcessor입니다.
• “모두 로컬”이라는 지향점과 원격 모델·임베딩·메신저·저장소를 사용할 때의 외부 통신은 구분해야 합니다.
• PostgreSQL 지원과 별개로 지식 색인은 로컬 SQLite이고, 버전형 기록에는 SQLite 제어 DB 제약이 있습니다.
• API 문서 UI는 기본 비활성화이며, Docker 프런트엔드 빌드는 전체 TypeScript 검사를 생략합니다.