Ultralytics Explorer API#

소개#

Explorer API는 데이터셋을 탐색하기 위한 Python API입니다. SQL 쿼리, 벡터 유사도 검색, 의미 검색을 사용해 데이터셋을 필터링하고 검색할 수 있습니다.

설치#

Explorer는 일부 기능에 외부 라이브러리를 사용합니다. Explorer를 사용하면 이러한 라이브러리가 자동으로 설치됩니다. 이 종속성을 수동으로 설치하려면 다음 명령을 사용합니다:

pip install "ultralytics[explorer]==8.3.11"

사용법#

from ultralytics import Explorer

# Explorer 객체 생성
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# 데이터셋 임베딩 생성
explorer.create_embeddings_table()

# 지정한 이미지와 유사한 이미지 검색
df = explorer.get_similar(img="path/to/image.jpg")

# 또는 지정한 인덱스와 유사한 이미지 검색
df = explorer.get_similar(idx=0)

임베딩 테이블을 강제로 업데이트하려면 create_embeddings_table 메서드에 force=True을 전달하면 됩니다.

고급 분석을 수행하기 위해 LanceDB 테이블 객체에 직접 액세스할 수 있습니다. 자세한 내용은 임베딩 테이블 작업 섹션을 참조하세요.

1. 유사도 검색#

유사도 검색은 주어진 이미지와 유사한 이미지를 찾는 기법입니다. 유사한 이미지에는 비슷한 임베딩이 있다는 개념에 기반합니다. 임베딩 테이블을 구축한 후 다음 방법 중 하나로 유사도 검색을 실행할 수 있습니다:

• 데이터셋의 지정된 인덱스 또는 인덱스 목록에서: exp.get_similar(idx=[1,10], limit=10)
• 데이터셋에 없는 이미지 또는 이미지 목록에서: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

입력이 여러 개인 경우 입력 임베딩의 집계값이 사용됩니다.

입력과 가장 유사한 데이터 포인트 중 limit개와 임베딩 공간에서의 거리를 포함하는 pandas DataFrame이 반환됩니다. 이 데이터셋을 사용해 추가 필터링을 수행할 수 있습니다.

from ultralytics import Explorer

# Explorer 객체 생성
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

similar = exp.get_similar(img="https://ultralytics.com/images/bus.jpg", limit=10)
print(similar.head())

# 여러 이미지를 사용해 검색
similar = exp.get_similar(
    img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
    limit=10,
)
print(similar.head())

유사 이미지 시각화#

plot_similar 메서드를 사용해 유사 이미지를 시각화할 수도 있습니다. 이 메서드는 get_similar과 동일한 인수를 받으며 유사 이미지를 그리드로 표시합니다.

from ultralytics import Explorer

# Explorer 객체 생성
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

plt = exp.plot_similar(img="https://ultralytics.com/images/bus.jpg", limit=10)
plt.show()

2. Ask AI(자연어 쿼리)#

이 기능을 사용하면 SQL을 작성하지 않고 자연어로 데이터셋을 필터링할 수 있습니다. AI 기반 쿼리 생성기는 프롬프트를 쿼리로 변환하고 일치하는 결과를 반환합니다. 예를 들어, "사람 한 명과 개 두 마리만 있는 이미지 100개를 보여 줘. 다른 객체가 있어도 괜찮아"라고 요청하면 쿼리를 생성하고 해당 결과를 표시합니다. 참고: 이 기능은 LLM을 사용하므로 결과는 확률적이며 부정확할 수 있습니다.

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# Explorer 객체 생성
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

df = exp.ask_ai("show me 100 images with exactly one person and 2 dogs. There can be other objects too")
print(df.head())

# 결과 시각화
plt = plot_query_result(df)
plt.show()

3. SQL 쿼리#

sql_query 메서드를 사용해 데이터셋에 SQL 쿼리를 실행할 수 있습니다. 이 메서드는 SQL 쿼리를 입력으로 받아 결과가 포함된 pandas DataFrame을 반환합니다.

from ultralytics import Explorer

# Explorer 객체 생성
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

df = exp.sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%'")
print(df.head())

SQL 쿼리 결과 시각화#

plot_sql_query 메서드를 사용해 SQL 쿼리 결과를 시각화할 수도 있습니다. 이 메서드는 sql_query과 동일한 인수를 받으며 결과를 그리드로 표시합니다.

from ultralytics import Explorer

# Explorer 객체 생성
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# SQL 쿼리 시각화
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. 임베딩 테이블 작업#

임베딩 테이블을 직접 사용할 수도 있습니다. 임베딩 테이블을 생성한 후 Explorer.table을 사용해 테이블에 액세스할 수 있습니다.

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()
table = exp.table

테이블을 사용해 수행할 수 있는 작업의 예시는 다음과 같습니다:

원시 임베딩 가져오기#

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()
table = exp.table

embeddings = table.to_pandas()["vector"]
print(embeddings)

사전 필터 및 사후 필터를 사용한 고급 쿼리#

from ultralytics import Explorer

exp = Explorer(model="yolo11n.pt")
exp.create_embeddings_table()
table = exp.table

# 더미 임베딩
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)

벡터 인덱스 생성#

대규모 데이터셋을 사용할 때는 더 빠른 쿼리를 위해 전용 벡터 인덱스를 생성할 수도 있습니다. 이는 LanceDB 테이블에서 create_index 메서드를 사용해 수행합니다.

table.create_index(num_partitions=..., num_sub_vectors=...)

5. 임베딩 활용#

임베딩 테이블을 사용해 다양한 탐색 분석을 수행할 수 있습니다. 몇 가지 예시는 다음과 같습니다:

유사도 인덱스#

Explorer에는 similarity_index 작업이 포함되어 있습니다:

• 이 작업은 각 데이터 포인트가 나머지 데이터셋과 얼마나 유사한지 추정합니다.
• 생성된 임베딩 공간에서 현재 이미지보다 max_dist만큼 가까운 이미지 임베딩의 개수를 계산하며, 한 번에 top_k개의 유사 이미지를 고려합니다.

다음 열을 포함하는 pandas DataFrame을 반환합니다:

• idx: 데이터셋에서 이미지의 인덱스
• im_file: 이미지 파일 경로
• count: 현재 이미지보다 max_dist만큼 가까운 데이터셋 이미지의 개수
• sim_im_files: count개의 유사 이미지 경로 목록

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

유사도 인덱스를 사용해 데이터셋을 필터링하는 사용자 지정 조건을 만들 수 있습니다. 예를 들어 다음 코드를 사용해 데이터셋의 다른 어떤 이미지와도 유사하지 않은 이미지를 필터링할 수 있습니다:

import numpy as np

sim_count = np.array(sim_idx["count"])
sim_idx["im_file"][sim_count > 30]

임베딩 공간 시각화#

원하는 플로팅 도구를 사용해 임베딩 공간을 시각화할 수도 있습니다. 다음은 Matplotlib을 사용하는 간단한 예시입니다:

import matplotlib.pyplot as plt
from sklearn.decomposition import PCA

# 3D 시각화를 위해 PCA를 사용해 차원을 3개 구성 요소로 축소
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Matplotlib Axes3D를 사용해 3D 산점도 생성
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# 산점도
ax.scatter(reduced_data[:, 0], reduced_data[:, 1], reduced_data[:, 2], alpha=0.5)
ax.set_title("3D Scatter Plot of Reduced 256-Dimensional Data (PCA)")
ax.set_xlabel("Component 1")
ax.set_ylabel("Component 2")
ax.set_zlabel("Component 3")

plt.show()

Explorer API를 사용해 나만의 컴퓨터 비전 데이터셋 탐색 보고서를 만들어 보세요. 아이디어를 얻으려면 VOC 탐색 예제를 확인하세요.

Ultralytics Explorer를 사용해 만든 앱#

Explorer API 기반 GUI 데모를 사용해 보세요.

자주 묻는 질문#