Python Library¶

akasicdb는 AkasicDB의 공식 Python client library입니다. Vector search를 위한 high-level SDK, Psycopg3 type registration, SQLAlchemy 및 Django integration, vector index option helper, graph query utility를 제공합니다.

실행 가능한 code path는 Python Library 예제에서 확인합니다.

요구 사항¶

Python 3.11 이상
실행 중인 AkasicDB instance
필요 시 table, index를 생성할 수 있는 database user

먼저 Quick Start를 참고하여 AkasicDB를 실행합니다.

설치¶

필요한 기능에 맞춰 package를 설치합니다.

pip install "akasicdb"
pip install "akasicdb[sdk]"
pip install "akasicdb[sqlalchemy]"
pip install "akasicdb[django]"
pip install "akasicdb[all]"

High-level AkasicDB client를 사용할 때는 akasicdb[sdk]를 설치합니다. 모든 integration을 함께 설치하려면 akasicdb[all]을 사용합니다.

Package version은 AkasicDB server version과 맞추는 것을 권장합니다.

AkasicDB version	권장 `akasicdb` version
`0.1.*`	`0.1.*`
`0.2.*`	`0.2.*`
`1.0.*`	`1.0.*`

Connection URL¶

High-level SDK와 SQLAlchemy integration은 SQLAlchemy connection URL을 사용합니다.

postgresql+psycopg://postgres:mysecretpassword@localhost:5432/postgres

Psycopg3 및 graph helper API는 Psycopg connection URL을 사용합니다.

postgresql://postgres:mysecretpassword@localhost:5432/postgres

Package 영역¶

영역	Import path	용도
High-level SDK	`akasicdb.sdk`	SQL을 직접 작성하지 않고 record 저장 및 vector search 수행
Psycopg3 integration	`akasicdb.psycopg`	Psycopg3에서 AkasicDB vector type 등록
SQLAlchemy integration	`akasicdb.sqlalchemy`	SQLAlchemy model에 vector column과 distance expression 정의
Django integration	`akasicdb.django`	Django model에 vector field, index, distance function 정의
Vector 및 index type	`akasicdb.types`	Vector value 및 index option string 생성
Graph utility	`akasicdb.graph`	AkasicDB를 통해 Cypher query 실행

대표적인 import는 다음과 같습니다.

from akasicdb.sdk import AkasicDB, Record
from akasicdb.psycopg import register_vector
from akasicdb.sqlalchemy import VECTOR
from akasicdb.django import VectorField
from akasicdb.types import Hnsw, IndexOption
from akasicdb.graph import execute_cypher

High-Level SDK¶

SDK는 text, metadata, embedding을 AkasicDB-backed collection에 저장합니다. collection_<collection_name> 이름의 table을 만들고, embedding column에 vector index를 생성할 수 있습니다.

from akasicdb.sdk import AkasicDB, Record

client = AkasicDB(DB_URL, "docs", dimension=3, create_vector_index=True)
client.insert([Record.from_text("hello akasicdb", [1.0, 2.0, 3.0])])
results = client.search([1.0, 2.0, 3.5], top_k=3)

주요 object는 다음과 같습니다.

Object	설명
`AkasicDB`	하나의 collection을 다루는 client
`Record`	Text, metadata, UUID, embedding container
`filters`	Metadata 및 text filter helper
`GraphQuery`	Fluent graph query builder
`SqlQuery`	Fluent SQL query builder
`ComposedQuery`	SQL/GQL composer

자주 쓰는 client operation은 다음과 같습니다.

Operation	Method
Record 삽입	`insert()`
Similarity search	`search()`
Record 조회	`get()`
Record 수 확인	`row_count()`
Record 삭제	`delete()`, `delete_by_ids()`, `delete_all()`
Collection table 삭제	`drop()`
Connection 정리	`close()`

search()는 <->, <=>, <#> distance operator를 지원합니다. Metadata filter는 $eq, $ne, $gt, $lt, $gte, $lte, $in, $nin, $and, $or를 사용할 수 있습니다.

전체 예제는 High-Level SDK를 참고하시기 바랍니다.

Psycopg3 Integration¶

Psycopg3를 직접 사용할 때는 akasicdb.psycopg.register_vector()를 사용합니다. Vector type을 등록하면 Psycopg가 AkasicDB vector 값을 Python object로 변환하고, Python 값을 SQL parameter로 bind할 수 있습니다.

import psycopg

from akasicdb.psycopg import register_vector

with psycopg.connect(DB_URL) as conn:
    register_vector(conn)
    conn.execute("INSERT INTO documents (embedding) VALUES (%s)", ([1, 2, 3],))

전체 예제는 Psycopg3를 참고하시기 바랍니다.

SQLAlchemy Integration¶

SQLAlchemy integration은 AkasicDB vector column type과 distance method를 제공합니다.

from sqlalchemy.orm import mapped_column

from akasicdb.sqlalchemy import VECTOR

class Document(Base):
    __tablename__ = "documents"
    embedding = mapped_column(VECTOR(3))

AkasicDB type	SQLAlchemy type
`vector`	`VECTOR`
`svector`	`SVECTOR`
`vecf16`	`VECF16`
`bvector`	`BVECTOR`

Distance method로 l2_distance, max_inner_product, cosine_distance를 사용할 수 있으며, binary vector에는 jaccard_distance도 사용할 수 있습니다.

전체 예제는 SQLAlchemy를 참고하시기 바랍니다.

Django Integration¶

Django integration은 model field, migration helper, vector index, distance function을 제공합니다.

from django.db import models

from akasicdb.django import L2Distance, VectorField

class Document(models.Model):
    embedding = VectorField(dim=3)

Document.objects.order_by(L2Distance("embedding", [1.0, 2.0, 3.0]))

AkasicDB type	Django field
`vector`	`VectorField`
`svector`	`SparseVectorField`
`vecf16`	`Float16VectorField`
`bvector`	`BinaryVectorField`

지원하는 index class에는 HnswIndex, IvfIndex, VamanaIndex가 있습니다.

전체 예제는 Django를 참고하시기 바랍니다.

Vector Type과 Index Option¶

akasicdb.types는 AkasicDB vector value와 index option을 위한 Python object를 제공합니다.

from akasicdb.types import Hnsw, IndexOption, SparseVector

sparse = SparseVector({0: 1.0, 2: 3.0}, 4)
options = IndexOption(index=Hnsw(m=16), threads=1).dumps()

주요 vector class는 다음과 같습니다.

Class	용도
`Vector`	Dense vector value
`SparseVector`	Sparse vector value
`Float16Vector`	Half-precision vector value
`BinaryVector`	Binary vector value

주요 index option class는 다음과 같습니다.

Class	용도
`IndexOption`	공통 option + index 종류별 option
`Flat`	Flat index option
`Hnsw`	HNSW index option
`Ivf`	IVF index option
`Vamana`	Vamana index option
`Quantization`	Quantization option

Graph Query Utility¶

Python에서 AkasicDB를 통해 Cypher를 실행하려면 akasicdb.graph.execute_cypher()를 사용합니다. SQL/GQL string을 직접 생성해 실행하고 싶다면 wrap_cypher_query()를 사용합니다.

from akasicdb.graph import execute_cypher

rows = execute_cypher(
    DB_URL,
    "retail_graph",
    "MATCH (n:v_item) RETURN n.name AS name",
)

전체 예제는 Graph Query를 참고하시기 바랍니다.