DocArray: 비정형 데이터 구조체

참고 사항(Note)
현재 보고 계신 README는 DocArray>0.30에 대한 것이며, 이는 DocArray 0.21과 몇 가지 중요한 변경 사항을 도입했습니다. 만약 이전 버전인 DocArray <=0.21을 계속 사용하고 싶다면, pip install docarray==0.21 명령어를 통해 설치해야 합니다. 더 자세한 정보는 코드베이스, 문서(documentation) 및 핫픽스 브랜치를 참조하십시오.

DocArray는 멀티모달 데이터의 표현(representation), 전송(transmission), 저장(storage), 그리고 검색(retrieval)을 위해 전문적으로 제작된 Python 라이브러리입니다. 멀티모달 AI 애플리케이션 개발에 맞게 설계되었으며, 그 구조는 광범위한 Python 및 머신러닝 생태계와의 원활한 통합을 보장합니다. 2022년 1월 기준으로 DocArray는 Apache License 2.0 하에 공개 배포되고 있으며, 현재 LF AI & Data Foundation 내의 샌드박스 프로젝트 지위를 누리고 있습니다.

• :fire: NumPy, PyTorch, TensorFlow, 그리고 **JAX**에 대한 네이티브 지원을 제공하여 특히 모델 훈련 시나리오에 대응합니다.
• :zap: **Pydantic**을 기반으로 하며, FastAPI 및 **Jina**와 같은 웹 및 마이크로서비스 프레임워크와 즉시 호환됩니다.
• :package: **Weaviate, Qdrant, ElasticSearch, Redis, Mongo Atlas, 그리고 **HNSWLib**와 같은 벡터 데이터베이스를 지원합니다.
• :chains: HTTP를 통해 JSON으로, 또는 **gRPC**를 통해 **Protobuf**로 데이터 전송을 허용합니다.

설치

CLI에서 DocArray를 설치하려면 다음 명령어를 실행하세요:

pip install -U docarray

참고
DocArray <=0.21 버전을 사용하려면 pip install docarray==0.21로 설치하고, 코드베이스와 문서(docs) 및 핫픽스 브랜치를 확인하세요.

시작하기

DocArray가 처음이신가요? 사용 사례와 배경에 따라 DocArray를 학습하는 여러 가지 방법이 있습니다:

• PyTorch 또는 TensorFlow에서 온 경우
• Pydantic에서 온 경우
• FastAPI에서 온 경우
• Jina에서 온 경우
• 벡터 데이터베이스에서 온 경우
• Langchain에서 온 경우

표현 (Represent)

DocArray는 데이터를 기계 학습에 본질적으로 맞는 방식으로 표현할 수 있도록 지원합니다.

이는 다양한 시나리오에서 특히 유용합니다:

• :running: 모델을 **학습(training)**하는 경우: 크기와 모양이 다른 텐서들을 다루고 있으며, 각각은 서로 다른 요소들을 나타냅니다. 이를 논리적으로 구성할 방법을 원합니다.
• :cloud: 모델을 **서비스(serving)**하는 경우: 예를 들어 FastAPI를 통해 서비스하고, API 엔드포인트를 정확하게 정의하고 싶을 때입니다.
• :card_index_dividers: 데이터를 **파싱(parsing)**하는 경우: 기계 학습 또는 데이터 과학 프로젝트에 향후 배포할 목적일 수 있습니다.

:bulb: Pydantic에 익숙하신가요? DocArray는 Pydantic 위에 구축되었을 뿐만 아니라, 완벽한 호환성을 유지한다는 것을 알게 되어 만족하실 것입니다!
게다가, 여러분의 필요를 위한 특정 섹션이 마련되어 있습니다!

본질적으로 DocArray는 Python dataclasses를 반영하는 방식으로 데이터 표현을 용이하게 하며, 기계 학습이 필수적인 구성 요소입니다:

from docarray import BaseDoc
from docarray.typing import TorchTensor, ImageUrl
import torch
...

DocArray를 사용하여 데이터를 어떻게 표현할 수 있는지 좀 더 자세히 살펴보겠습니다:

from docarray import BaseDoc
from docarray.typing import TorchTensor, ImageUrl
from typing import Optional
...

따라서 데이터의 타입을 정의할 수 있을 뿐만 아니라, 텐서의 **모양(shape)**까지 지정할 수 있습니다!

중첩된 Documents 구성하기

물론, Documents를 중첩 구조로 구성할 수도 있습니다:

from docarray import BaseDoc
from docarray.documents import ImageDoc, TextDoc
import numpy as np
...

거의 한 번에 하나의 데이터 포인트만 다루는 경우는 드물며, 특히 머신러닝(ML) 애플리케이션에서는 더욱 그렇습니다. 이것이 바로 여러 개의 Documents를 쉽게 수집할 수 있는 이유입니다:

여러 개의 Documents 수집하기

ML 시스템을 구축하거나 상호 작용할 때, 일반적으로 한 번에 여러 Documents (데이터 포인트)를 처리하길 원합니다.

DocArray는 이를 위해 두 가지 데이터 구조를 제공합니다:

• DocVec: Documents의 벡터입니다. 문서 내의 모든 텐서(tensor)가 단일 텐서로 쌓입니다. 배치 처리 및 ML 모델 내부 사용에 완벽합니다.
• DocList: Documents의 리스트입니다. 문서 내의 모든 텐서는 그대로 유지됩니다. 데이터 스트리밍, 재순위 지정(re-ranking), 데이터 셔플링에 완벽합니다.

DocVec부터 살펴보겠습니다:

from docarray import DocVec, BaseDoc
from docarray.typing import AnyTensor, ImageUrl
import numpy as np
...

위 코드 스니펫에서 DocVec은 사용하려는 문서의 타입으로 매개변수화(parametrized)됩니다: DocVec[Image].

처음에는 이상해 보일 수 있지만, 금방 익숙해지실 것이라 확신합니다! 게다가, 사용자가 정의한 필드에 대한 **벌크 액세스(bulk access)**와 같은 멋진 기능들을 할 수 있게 해줍니다:

tensor = vec.tensor  # DocVec 내의 모든 텐서를 가져옵니다
print(tensor.shape)  # 단일 텐서로 쌓여 있습니다!
print(vec.url)  # 다른 필드도 벌크 액세스할 수 있습니다

두 번째 데이터 구조인 DocList도 유사하게 작동합니다:

from docarray import DocList

dl = DocList[Image](  # DocList는 개인 스키마로 매개변수화됩니다!
...

여전히 문서의 필드에 대한 벌크 액세스를 할 수 있습니다:

tensors = dl.tensor  # DocList의 모든 텐서를 가져옵니다
print(type(tensors))  # 텐서 리스트로 출력됩니다
print(dl.url)  # 다른 필드도 일괄적으로 접근할 수 있습니다

그리고 DocList에 문서를 삽입, 제거 및 추가할 수 있습니다:

# 추가 (append)
dl.append(
    Image(
...

또한 DocVec와 DocList 사이를 원활하게 전환할 수 있습니다:

vec_2 = dl.to_doc_vec()
assert isinstance(vec_2, DocVec)

...

전송 (Send)

DocArray는 데이터를 기계 학습과 본질적으로 호환되는 방식으로 전송할 수 있도록 지원합니다.

여기에는 Protobuf 및 gRPC에 대한 네이티브 지원은 물론, HTTP와 JSON, JSONSchema, Base64, Bytes로의 직렬화(serialization)도 포함됩니다.

이 기능은 여러 시나리오에서 유용함을 입증합니다:

• :cloud: 모델을 서비스하는 경우, 예를 들어 Jina 또는 **FastAPI**와 같은 프레임워크를 통해
• :spider_web: 여러 머신에 걸쳐 모델을 배포하고 노드 간 데이터를 효율적으로 전송해야 하는 경우
• :gear: 마이크로서비스(microservice) 환경을 설계하며 마이크로서비스 간 데이터 전송 방법이 필요한 경우

:bulb: FastAPI에 익숙하신가요? DocArray가 FastAPI와 완벽하게 호환된다는 것을 알게 되면 기뻐하실 겁니다!
게다가, 여러분만을 위한 전용 섹션도 마련되어 있습니다!

데이터 전송과 관련하여 직렬화(serialization)는 매우 중요한 단계입니다. DocArray가 이 과정을 어떻게 간소화하는지 자세히 살펴보겠습니다:

from docarray import BaseDoc
from docarray.typing import ImageTorchTensor
import torch
...

물론 직렬화만으로는 충분하지 않습니다. 따라서 DocArray가 Jina 및 **FastAPI**와 어떻게 통합되는지 확인해 보세요.

저장 (Store)

데이터를 모델링하고 어쩌면 배포한 후, 일반적으로 그 데이터를 어딘가에 저장하기를 원할 것입니다. 바로 여기에 DocArray가 필요한 순간입니다!

Document Stores는 이름에서 알 수 있듯이 문서를 저장하는 원활한 방법을 제공합니다. 로컬이든 원격이든, 동일한 사용자 인터페이스를 통해 모든 것을 처리할 수 있습니다:**

• :cd: 디스크 상에, 로컬 파일 시스템의 파일로
• :bucket: **AWS S3**에서
• :cloud: **Jina AI Cloud**에서

Document Store 인터페이스를 사용하면 동일한 사용자 인터페이스로 여러 데이터 소스에 문서를 푸시(push)하고 풀(pull)할 수 있습니다.

예를 들어, 온디스크 스토리지와 함께 작동하는 방식을 살펴보겠습니다:

from docarray import BaseDoc, DocList

class SimpleDoc(BaseDoc):
...

검색 (Retrieve)

Document Indexes는 문서를 **벡터 데이터베이스(vector database)**에 인덱싱하여 효율적인 유사성 기반 검색을 가능하게 합니다.

이는 다음 경우에 유용합니다:

• :left_speech_bubble: 도메인 지식으로 LLM 및 챗봇(Chatbots) 증강 (검색 증강 생성, Retrieval Augmented Generation)
• :mag: 신경 검색(Neural search) 애플리케이션
• :bulb: 추천 시스템(Recommender systems)

현재 Document Indexes는 Weaviate, Qdrant, ElasticSearch, Redis, Mongo Atlas, 그리고 **HNSWLib**를 지원하며, 더 많은 기능이 추가될 예정입니다!

Document Index 인터페이스를 사용하면 동일한 사용자 인터페이스로 여러 벡터 데이터베이스에서 문서를 인덱싱하고 검색할 수 있습니다.

이는 ANN 벡터 검색(ANN vector search), 텍스트 검색(text search), 필터링(filtering), 하이브리드 검색(hybrid search)을 지원합니다.

from docarray import DocList, BaseDoc
from docarray.index import HnswDocumentIndex
import numpy as np
...

DocArray 학습하기 (Learn DocArray)

사용자의 배경과 사용 사례에 따라 DocArray를 이해하는 여러 가지 방법이 있습니다.

DocArray <=0.21에서 온 경우

DocArray 버전 0.30.0 이하를 사용하는 경우, dataclass API에 익숙하실 것입니다.

DocArray >=0.30에서 이 아이디어가 진지하게 다루어지고 있습니다. 모든 문서는 Pydantic의 데이터클래스(dataclass)와 같은 인터페이스를 통해 생성됩니다.

이는 다음과 같은 장점을 제공합니다:

• 유연성 (Flexibility): 고정된 필드 세트에 맞출 필요가 없습니다. 사용자의 데이터가 스키마를 정의합니다.
• 다중 모달리티 (Multimodality): 근본적으로 문서는 단순한 딕셔너리(dictionary)입니다. 이 덕분에 Python뿐만 아니라 어떤 언어에서도 쉽게 생성하고 전송할 수 있습니다.

또한, 벡터 DB 통합을 위한 저희의 이전 Document Store에 대해 알고 계실 수도 있습니다. 이제 이것들은 Document Indexes라고 불리며 다음과 같은 개선 사항을 제공합니다 (새로운 API는 여기를 참조하십시오):

• 하이브리드 검색 (Hybrid search): 벡터 검색과 텍스트 검색을 결합할 수 있으며, 임의의 필드로 필터링까지 할 수 있습니다.
• 프로덕션 준비 완료 (Production-ready): 새로운 Document Indexes는 다양한 벡터 DB 라이브러리를 감싸는 훨씬 더 얇은(thinner) 래퍼(wrapper) 역할을 하여, 더욱 견고하고 유지보수가 쉬워졌습니다.
• 향상된 유연성 (Increased flexibility): 저희는 사용자가 DB의 공식 클라이언트(first-party client)를 통해 수행할 수 있는 모든 구성이나 설정을 지원하기 위해 노력합니다.