주요 콘텐츠로 건너뛰기
버전: 2.0.0

개발자 문서 AI 에이전트

일반적으로 AI 에이전트는 어떤 일을 할 수 있고 약간 똑똑한 봇으로 간주됩니다. 하지만 실제로 가장 유용한 개발자 에이전트는 고도로 선별된 비공개 지식을 갖춘 매우 집중적인 전문 에이전트입니다. 예를 들어 프로그래밍 언어의 공식 문서나 프로토콜/회사의 내부 API 참조 등이 있습니다.

Gaia는 누구나 복잡한 과정 없이 전문 상담원을 만들 수 있는 세 가지 요소를 제공합니다. 청크를 드롭할 수 있는 플러그형 지식창고, OPENAI 스타일의 v1/chat/완성 및 모듈식 시스템 프롬프트를 말하는 RAG 인식 채팅 스택이 있습니다.

바이퍼 스마트 컨트랙트 언어 문서화 에이전트​

이제 Vyper 스마트 컨트랙트 언어 (솔리디티의 파이썬 기반 대안)를 위한 에이전트를 생성해 보겠습니다. 디렉터리 레이아웃, 임베딩 명령, 노드 구성 플래그 등 여기에 표시되는 모든 것이 다른 문서 집합으로 일대일로 번역됩니다: Rust 책 챕터, Django REST API 문서, RFC 아카이브 또는 모든 문서.

도커가 실행 중인지 확인하고 벡터 큐드런트 실행하여 설치 도커 풀 큐드런트/큐드런트

전제 조건: 한 번 설치한 툴링​

WasmEdge 런타임 - Gaia의 임베딩 유틸리티는 경량 WebAssembly 모듈로 제공되며, WasmEdge는 Linux/macOS/Windows에서 기본적으로 실행되는 실행 엔진입니다:

curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install_v2.sh | bash -s

왜 Wasm인가? pip 설치가 필요 없는 빌드 아티팩트(단일 .wasm 파일)를 얻을 수 있기 때문입니다. 보안 팀은 결정론적 바이너리를 좋아하고 DevOps는 제로 종속성 스토리를 좋아합니다.

모델 가중치 포함 - 768차원의 문장 벡터를 생성하는 모델은 허깅 페이스에 있습니다:

curl -LO https://huggingface.co/gaianet/Nomic-embed-text-v1.5-Embedding-GGUF/resolve/main/nomic-embed-text-v1.5.f16.gguf

이러한 가중치는 디스크에서 효율적으로 스트리밍하고 CPU 전용 박스에 대한 정량화된 변형을 지원하는 GGML의 최신 후속작인 GGUF 형식으로 되어 있습니다.

두 개의 폴더를 다음과 같이 만들어 보겠습니다. qdrant_storage 그리고 큐드랜트_스냅샷 . 스냅샷으로 정리된 지식창고는 다음과 같습니다. 큐드랜트_스냅샷.

mkdir qdrant_storage
mkdir qdrant_snapshots

nohup docker run -d -p 6333:6333 -p 6334:6334 \.
    -v $(pwd)/qdrant_storage:/qdrant/storage:z \.
    -v $(pwd)/qdrant_snapshots:/qdrant/snapshots:z \ \.
    qdrant/qdrant

몇 가지 모범 사례 참고 사항입니다:

  • 대량 업로드를 스크립팅하거나 Rust/Go Qdrant 클라이언트로 벤치마크를 실행할 예정이라면 6333(REST/JSON) 및 6334(gRPC)를 맵으로 만드세요.
  • 마운트된 볼륨에 qdrant_storage를 유지한다는 것은 컨테이너 재시작 후에도 벡터가 살아남아 나중에 스냅샷을 위해 tar-gz할 수 있다는 뜻입니다.

컬렉션 만들기​

기본 Gaia 샘플 수집은 다른 차원 크기를 사용하기 때문에 새로 시작해야 합니다.

데이터가 있는 경우 삭제해 보겠습니다:

# 지우기 오래된 데이터
curl -X DELETE 'http://localhost:6333/collections/default'

그런 다음 다음을 실행합니다.


# Provision a 768-dimensional, cosine-distance space
curl -X PUT 'http://localhost:6333/collections/default' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "vectors": {
      "size": 768,
      "distance": "Cosine",
      "on_disk": true
    }
  }'

말뭉치가 수십만 개의 덩어리로 커질 때 on_disk 플래그는 여러분의 친구입니다. Qdrant는 벡터를 메모리 매핑하고 LLM을 위해 RAM을 남깁니다.

임베딩 제작하기​

임베딩 CLI 살펴보기

curl -LO https://github.com/GaiaNet-AI/embedding-tools/raw/main/csv_embed/csv_embed.wasm

문서 준비는 다음과 같이 하세요.​

왜 마크다운 대신 CSV를 사용하나요?  저는 마크다운보다 CSV를 사용하는 것이 더 쉬웠고, 각 청크를 다른 열에 붙여넣고 열당 하나의 셀에 붙여넣는 것이 더 좋다는 것을 알게 되었습니다. 자유롭게 사용 llm_info.txt 파일에 저장할 수 있습니다.

저는 gitingest를 사용하여 바이퍼 문서 git 저장소를 코드베이스의 간단한 텍스트 다이제스트로 변환했는데, 이는 코드베이스/문서를 LLM에 공급하는 데 정말 유용합니다.

벡터 생성​

csv 파일과 llm_info.txt 파일이 같은 디렉토리에 있는지 확인하고 벡터를 생성해 봅시다.

wasmedge --dir ... \
  --nn-preload embedding:GGML:AUTO:nomic-embed-text-v1.5.f16.gguf \.
  csv_embed.wasm 임베딩 기본값 768 your_docs.csv --ctx_size 8192
  • 깃발의 분류:
    • -dir ...은 작업 디렉터리에 대한 읽기/쓰기 권한을 와즘 샌드박스에 부여하여 CSV를 스트리밍하고 벡터를 Qdrant에 다시 쓸 수 있도록 합니다.
    • -nn-preload embedding:GGML:AUTO:...는 모델을 한 번 미리 로드하여 1,000개 청크당 약 2초를 절약합니다.
    • ctx_size는 채팅 모델이 아닌 임베딩 모델 내부에서 사용되는 보조 토큰 창으로, 문서 단락이 길고 로그에 잘림이 표시되는 경우 크랭크업합니다.

start_vector_id와 함께 명령을 여러 번 실행하여 충돌 없이 새 샤드를 추가할 수 있으며, 분기별 문서 업데이트를 계획하는 경우 Qdrant ID는 정수가 되므로 100_000과 같은 오프셋을 지정하세요.

지식창고 패키징 및 배포​

스냅샷은 Qdrant가 원자 단위로 복원할 수 있는 JSON 및 Parquet 파일의 디렉토리에 불과합니다. 벡터는 매우 반복적이기 때문에 압축하면 일반적으로 3 대 1 크기의 이점을 얻을 수 있습니다.

curl -X POST 'http://localhost:6333/collections/default/snapshots'

이제 스냅샷을 압축할 차례입니다. qdrant_snapshots/default 를 클릭한 다음 실행하여 압축합니다.

tar czvf my.스냅샷.tar.gz my.스냅샷

대신 내.스냅샷 파일 이름을 사용하기만 하면 됩니다. huggingface에 my.snapshot.tar.gz를 업로드하려면 계정이 있어야 합니다. 이제 새 데이터 집합을 클릭하고 거기에 지식창고를 업로드합니다.

몇 가지 모범 사례(어려운 과정을 통해 배운)​

  1. 청크 전략

    벡터당 200-500개의 토큰을 목표로 하세요. 너무 짧으면 거의 동일한 수천 개의 임베딩(노이즈)이 인덱스에 넘쳐납니다. 너무 길면 검색 단계에서 모델이 완전히 읽지 못한 거대한 블록이 반환됩니다.

  2. 시스템 프롬프트 엔지니어링

    구문 기능 및 가드레일. 예시:

    "귀하는 Vyper 언어 도우미입니다. Vyper가 아닌 질문을 받으면 한 문장으로 정중하게 사과하며 거절하세요. 모든 답변에 코드 라인 번호를 인용하세요."

  3. 지속적인 평가 루프

    실제 사용자 쿼리를 스프레드시트에 입력하고 '도움이 됨/도움이 되지 않음'이라는 라벨을 붙인 다음 패턴을 살펴보세요. 사람들이 구문보다 보안 모범 사례를 더 많이 묻는가? 그러면 어떤 문서 섹션에 더 풍부한 예시가 필요한지 알 수 있습니다.

지식창고를 허깅페이스에 업로드한 후에는 이제 llm의 지식창고를 변경할 차례입니다. 아직 자체 노드를 실행하기 위해 변경하지 않았다면 여기로 이동하여 시작할 수 있습니다.

특정 노드를 햇볕에 쬐고 싶다면 여기로 가서 저에게 적합한 LLM을 선택해 보겠습니다.

설치 후 다음을 실행해야 합니다:

가이아넷 구성 \
  --스냅샷 https://huggingface.co/데이터 세트/meowy-ai/vyper-lang/resolve/main/기본값-845259036638694-2025-04-22-09-28-18.스냅샷.tar.gz \
  --system-프롬프트 "당신은 도움이 되는 바이퍼 랭 강사입니다, 질문에 답해 주세요"

여기 --스냅샷 https://huggingface.co/... 은 제가 허깅페이스에 업로드한 지식창고의 다운로드 링크입니다.

단말기에 다음과 같은 메시지가 표시됩니다:


[+] 업데이트 시스템 프롬프트 의 채팅 모델 ...
    * Old 시스템 프롬프트: You 는 유용한 바이퍼 랭 강사입니다., 질문에 답해 주세요
    * 신규 시스템 프롬프트: You 는 유용한 웹3.0 강사, 질문에 답해 주세요

[+] 업데이트 URL 의 스냅샷 ...
    * Old url: https://huggingface.co/데이터 세트/meowy-ai/web3-지식-base/resolve/main/기본값-8461598741381726-2025-04-29-07-50-41.스냅샷.tar.gz
    * New url: https://huggingface.co/데이터 세트/meowy-ai/vyper-lang/resolve/main/기본값-845259036638694-2025-04-22-09-28-18.스냅샷.tar.gz

✅ COMPLETED! 그리고 config.json 이 성공적으로 업데이트되었습니다..

이제 다음을 사용하여 가이아 노드를 시작해야 합니다. 가이아넷 시작.

이제 노드는 방금 업데이트한 vyper 지식창고를 사용합니다. 문서 에이전트를 성공적으로 만들었습니다.