본문으로 건너뛰기

개발

Khoj 개발 문서에 오신 것을 환영합니다! 기여자로서 관심을 가져주셔서 감사합니다 ❤️. 오픈 소스 기여자는 Khoj 커뮤니티의 초석입니다. 크고 작든 모든 기여를 환영합니다.

기여를 시작하려면 오픈 소스 프로젝트에 기여하기에 대한 공식 GitHub 문서를 확인하세요.

Discord 서버에 가입하고 #welcome-and-rules 채널에서 "기여자가 되는 데 관심이 있으신가요?" 질문에 ✅를 클릭하세요. 이렇게 하면 #contributors 채널에 접근할 수 있으며, 여기서 질문하고 다른 기여자로부터 도움을 받을 수 있습니다.

시작할 곳을 찾고 있다면 good first issue 태그가 있는 Github 이슈 목록을 확인하여 첫 기여자에게 좋은 이슈를 찾으세요.

로컬 서버 설치​

Pip 사용​

1. Khoj 설치​

# Get Khoj Code
git clone https://github.com/khoj-ai/khoj && cd khoj

# Create, Activate Virtual Environment
python3 -m venv .venv && source .venv/bin/activate

# For MacOS or zsh users run this
pip install -e '.[dev]'

2. Postgres 설치 및 설정​

Khoj는 Postgres 데이터베이스에 인덱스의 임베딩을 저장하기 위해 pgvector 패키지를 사용합니다. 이를 사용하려면 Postgres가 설치되어 있어야 합니다.

Postgres.app을 설치합니다. 여기에는 pgvector 및 관련 종속성이 미리 설치되어 있습니다.

Khoj 데이터베이스 생성​

다른 이름을 사용하는 경우 Postgres 구성과 일치하도록 환경 변수를 업데이트해야 합니다. 기본값은 대부분의 사용자에게 작동합니다. 암호를 묻는 메시지가 나타나면 기본 암호 postgres를 사용하거나 원하는 대로 구성할 수 있습니다. POSTGRES_PASSWORD 환경 변수를 여기에 설정한 암호와 동일한 값으로 설정해야 합니다.

createdb khoj -U postgres --password

3. 프론트엔드 자산 빌드​

cd src/interface/web/
yarn install
yarn export

선택적으로 yarn dev를 사용하여 프론트엔드 개발 서버를 시작할 수 있으며, 이 서버는 http://localhost:3000에서 사용할 수 있습니다. 이는 프론트엔드 코드를 변경할 때 특히 유용하지만 Khoj를 실행하는 데는 필요하지 않습니다. Next.js의 SSR 처리 방식 때문에 개발 서버에서는 스트리밍이 작동하지 않습니다.

PR을 생성하기 전에 항상 yarn export를 실행하여 http://localhost:42110에서 프론트엔드 변경 사항을 테스트하세요.

4. 실행​

  1. Khoj 시작 
    khoj -vv
  2. Khoj 구성
    • 데스크톱 애플리케이션을 통해: 데스크톱 애플리케이션의 설정 페이지를 사용하여 색인할 파일, 디렉토리를 추가합니다. "저장"을 클릭하여 즉시 색인을 트리거합니다.

참고: 구성 후 Khoj가 ML 모델을 로드하고, 임베딩을 생성하고, 구성 YAML에 지정된 노트, 이미지, 문서 등을 쿼리할 API를 노출할 때까지 기다리세요.

Windows 설치 노트​

  1. khoj 명령이 인식되지 않음
    • 가상 환경을 다시 활성화하고 khoj 명령을 다시 실행해 보세요.
    • 여전히 작동하지 않으면 설치 프로세스를 반복합니다.
  2. Python 패키지 누락
    • pip install xxx를 사용하고 khoj 명령을 실행해 보세요.
  3. createdb 명령이 인식되지 않음
    • postgres 바이너리 경로가 환경 변수에 포함되어 있는지 확인합니다. 일반적으로 다음과 같습니다.
    C:\Program Files\PostgreSQL\16\bin
  4. 포트 xxxx에서 연결 거부됨
    • postgres가 설치된 위치에서 pg_hba.conf 파일을 찾습니다.
    • 파일을 편집하여 사용자 postgres, local 및 host 연결에 대한 메서드를 trust로 설정합니다.
    • 다음은 예시입니다:
host    all             postgres        127.0.0.1/32            trust
# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
host    all             all             ::1/128                 trust
  1. pgvector 설치 오류
    • Visual Studio 2022 빌드 도구를 다음으로 다시 설치합니다:
      1. 워크로드에서 c++를 사용한 데스크톱 개발 선택
      2. 개별 구성 요소에서 MSVC (C++ 빌드 도구), Windows 10/11 SDK 및 빌드 도구용 C++/CLI 지원 선택
    • x64 Native Tools Command Prompt를 관리자 권한으로 엽니다.
    • 이 명령 프롬프트에서 pgvector windows 설치 지침을 따릅니다.

Docker 사용​

최신 버전의 Docker 및 Docker Compose를 설치했는지 확인하세요.

1. 클론​

git clone https://github.com/khoj-ai/khoj && cd khoj

2. 구성​

  1. docker-compose.yml을 업데이트하여 관련 환경 변수를 사용합니다.
  2. server 서비스에서 image 줄을 주석 처리하고 build 줄의 주석을 해제합니다.

3. 실행​

이렇게 하면 Khoj 서버와 데이터베이스가 시작됩니다.

docker-compose up -d

4. 업그레이드​

코드베이스를 변경한 경우 컨테이너를 다시 실행하기 전에 Docker 이미지를 다시 빌드해야 합니다.

docker-compose build --no-cache

클라이언트 업데이트​

테스트에 사용하는 클라이언트에서 서버 URL을 로컬 서버를 가리키도록 업데이트해야 합니다. 기본적으로 로컬 서버 URL은 http://127.0.0.1:42110이어야 합니다.

유효성 검사​

변경 전​

  1. Khoj 설치. 유효성 검사를 위한 Git Hooks 설정 
    ./scripts/dev_setup.sh
    • 기본적으로 khoj 서버 및 웹 앱을 설치합니다. --full 플래그를 사용하여 Khoj 데스크톱 및 Obsidian 클라이언트 앱도 설치합니다.
    • Git hooks는 모든 커밋 및 푸시 시 코드를 자동으로 포맷하고 유형을 확인합니다.
    • 참고 1: pre-commit이 아직 설치되지 않은 경우 pip install pre-commit을 통해 설치합니다.
    • 참고 2: PR을 생성하기 전에 pre-commit run --hook-stage manual --all을 사용하여 pre-commit 변경 사항을 수동으로 실행합니다.

PR 생성 전​

참고

단위 테스트 및 린터를 실행하려면 Khoj에 대한 활성 가상 환경에 있어야 합니다. dev_setup.sh 스크립트는 자동으로 이를 생성하고 활성화합니다.

  1. PR에 연결할 수 있는 Github 이슈가 있는지 확인합니다. 없는 경우 생성합니다. 이슈에 유지 관리자 중 한 명을 태그했는지 확인합니다. 이렇게 하면 유지 관리자에게 PR이 알림되고 검토할 수 있습니다. PR을 생성하기 전에 기존 이슈 또는 Discord 스레드에서 코드 디자인을 논의하는 것이 가장 좋습니다. 이렇게 하면 PR이 더 빨리 병합됩니다.
  2. 단위 테스트를 실행합니다. 
    pytest
  3. 린터를 실행합니다. 
    mypy
  4. PR에 추가하는 기능을 확인하기 위해 단위 테스트를 추가하는 방법을 고려합니다. 방법을 잘 모르겠다면 Github 이슈 또는 Discord의 #contributors 채널에서 도움을 요청하세요.

PR 생성 후​

  1. 모든 PR에 대해 자동화된 유효성 검사 워크플로가 실행되어야 합니다. PR에서 유지 관리자 중 한 명을 태그하여 트리거합니다.

Obsidian 플러그인 개발​

플러그인 개발 설정​

Obsidian 플러그인의 핵심 코드는 src/interface/obsidian 아래에 있습니다. main.ts 파일은 시작하기 좋은 곳입니다.

  1. CLI에서 Khoj 저장소의 src/interface/obsidian 디렉토리로 이동합니다.
  2. yarn install을 실행하여 종속성을 설치합니다.
  3. yarn dev를 실행하여 개발 서버를 시작합니다. 이렇게 하면 코드를 변경할 때마다 플러그인이 계속 다시 빌드됩니다.
    • 코드 변경 사항은 obsidian 디렉토리에 main.js라는 파일로 출력됩니다.

Obsidian에서 개발 플러그인 로드​

  1. Obsidian에 Khoj 플러그인이 설치되어 있는지 확인합니다. 플러그인 페이지를 참조하세요.
  2. Obsidian을 열고 설정(왼쪽 하단 모서리의 톱니바퀴 아이콘)으로 이동합니다.
  3. 왼쪽 패널에서 '커뮤니티 플러그인'을 클릭합니다.
  4. '설치된 플러그인' 제목 옆에 있는 폴더 아이콘을 클릭하여 플러그인의 소스 코드가 있는 폴더를 엽니다.
  5. 열리는 파일 탐색기에서 khoj 폴더를 엽니다. 이 폴더에 main.js라는 파일이 있습니다. 변경 사항을 테스트하려면 이 파일을 이전 섹션에서 개발 서버가 생성한 main.js 파일로 바꿉니다.

Khoj 릴리스 생성 (유지 관리자만 해당)​

Khoj를 릴리스하려면 아래 단계를 따르세요. 이렇게 하면 Pypi, Melpa 및 Obsidian에 Khoj의 안정적인 릴리스가 생성됩니다. 또한 Khoj의 데스크톱 앱을 생성하고 최신 릴리스에 첨부합니다.

  1. bump_version 스크립트를 실행하여 릴리스 커밋을 생성하고 태그를 지정합니다. 릴리스 커밋은 필요한 메타데이터 파일에 버전 번호를 설정합니다.
./scripts/bump_version.sh -c "<release_version>"
  1. 커밋을 푸시한 다음 태그를 푸시하여 릴리스 워크플로를 트리거하여 자동 생성된 릴리스 노트로 릴리스를 생성합니다.
git push origin master  # khoj 저장소에 릴리스 커밋 푸시
git push origin <release_version>  # khoj 저장소에 릴리스 태그 푸시
  1. [선택 사항] 새 기능, 수정 사항 및 업데이트를 강조하기 위해 릴리스 노트를 업데이트합니다.

아키텍처​

코드베이스 시각화​

대화형 시각화

Khoj Obsidian 플러그인 코드베이스 시각화​