All Products
Search
Document Center

DashVector:Dokumentasi Pengambilan Berkelompok

Last Updated:Apr 01, 2026

Gunakan metode query_group_by() untuk mencari koleksi dan mengelompokkan hasil berdasarkan nilai bidang tertentu. Fitur ini berguna dalam pipeline Retrieval-Augmented Generation (RAG), di mana satu dokumen dibagi menjadi beberapa chunk—tanpa pengelompokan, hasil teratas mungkin berisi beberapa chunk dari dokumen yang sama, sehingga dokumen lain kurang terwakili.

Prasyarat

Sebelum memulai, pastikan Anda telah memiliki:

Definisi API

Collection.query_group_by(
        self,
        vector: Optional[Union[List[Union[int, float]], np.ndarray]] = None,
        *,
        group_by_field: str,
        group_count: int = 10,
        group_topk: int = 10,
        id: Optional[str] = None,
        filter: Optional[str] = None,
        include_vector: bool = False,
        partition: Optional[str] = None,
        output_fields: Optional[List[str]] = None,
        sparse_vector: Optional[Dict[int, float]] = None,
        async_req: bool = False,
    ) -> DashVectorResponse:

Contoh

Ganti YOUR_API_KEY dengan kunci API Anda dan YOUR_CLUSTER_ENDPOINT dengan titik akhir kluster Anda sebelum menjalankan contoh berikut.

Semua contoh di bawah ini menggunakan set data yang sama. Jalankan kode penyiapan berikut terlebih dahulu untuk membuat koleksi dan memasukkan data sampel:

import dashvector
import numpy as np

client = dashvector.Client(
    api_key='YOUR_API_KEY',
    endpoint='YOUR_CLUSTER_ENDPOINT'
)
ret = client.create(
    name='group_by_demo',
    dimension=4,
    fields_schema={'document_id': str, 'chunk_id': int}
)
assert ret

collection = client.get(name='group_by_demo')

ret = collection.insert([
    ('1', np.random.rand(4), {'document_id': 'paper-01', 'chunk_id': 1, 'content': 'xxxA'}),
    ('2', np.random.rand(4), {'document_id': 'paper-01', 'chunk_id': 2, 'content': 'xxxB'}),
    ('3', np.random.rand(4), {'document_id': 'paper-02', 'chunk_id': 1, 'content': 'xxxC'}),
    ('4', np.random.rand(4), {'document_id': 'paper-02', 'chunk_id': 2, 'content': 'xxxD'}),
    ('5', np.random.rand(4), {'document_id': 'paper-02', 'chunk_id': 3, 'content': 'xxxE'}),
    ('6', np.random.rand(4), {'document_id': 'paper-03', 'chunk_id': 1, 'content': 'xxxF'}),
])
assert ret

Pencarian berdasarkan vektor

Berikan vektor kueri dan tentukan bidang yang digunakan untuk pengelompokan. Gunakan group_count untuk mengatur jumlah kelompok yang dikembalikan, dan group_topk untuk mengatur jumlah hasil per kelompok.

ret = collection.query_group_by(
    vector=[0.1, 0.2, 0.3, 0.4],
    group_by_field='document_id',  # Kelompokkan hasil berdasarkan bidang document_id.
    group_count=2,                 # Kembalikan hingga dua kelompok.
    group_topk=2,                  # Kembalikan hingga dua hasil per kelompok.
)
if ret:
    print('query_group_by success')
    print(len(ret))
    print('------------------------')
    for group in ret:
        print('group key:', group.group_id)
        for doc in group.docs:
            prefix = ' -'
            print(prefix, doc)

Output yang diharapkan:

query_group_by success
4
------------------------
group key: paper-01
 - {"id": "2", "fields": {"document_id": "paper-01", "chunk_id": 2, "content": "xxxB"}, "score": 0.6807}
 - {"id": "1", "fields": {"document_id": "paper-01", "chunk_id": 1, "content": "xxxA"}, "score": 0.4289}
group key: paper-02
 - {"id": "3", "fields": {"document_id": "paper-02", "chunk_id": 1, "content": "xxxC"}, "score": 0.6553}
 - {"id": "5", "fields": {"document_id": "paper-02", "chunk_id": 3, "content": "xxxE"}, "score": 0.4401}

Tanggapan berisi dua kelompok (paper-01 dan paper-02), masing-masing berisi hingga dua hasil yang diurutkan berdasarkan skor kemiripan.

Pencarian berdasarkan kunci primer

Gunakan parameter id untuk melakukan pencarian berkelompok berdasarkan vektor yang tersimpan untuk dokumen tertentu.

ret = collection.query_group_by(
    id='1',
    group_by_field='name',
)
if ret:
    print('query_group_by success')
    print(len(ret))
    for group in ret:
        print('group:', group.group_id)
        for doc in group.docs:
            print(doc)
            print(doc.id)
            print(doc.vector)
            print(doc.fields)

Pencarian dengan filter

Gabungkan vektor atau kunci primer dengan ekspresi filter untuk mempersempit hasil sebelum pengelompokan. Filter harus mengikuti sintaksis klausa WHERE SQL.

ret = collection.query(
    vector=[0.1, 0.2, 0.3, 0.4],   # Gunakan id='...' sebagai gantinya untuk mencari berdasarkan kunci primer.
    group_by_field='name',
    filter='age > 18',              # Kembalikan hanya dokumen dengan usia lebih dari 18.
    output_fields=['name', 'age'],  # Kembalikan hanya bidang name dan age.
    include_vector=True
)

Untuk sintaksis filter lengkap, lihat Conditional filtering.

Pencarian dengan vektor padat dan jarang

Sertakan kedua parameter vector dan sparse_vector untuk menggabungkan pengambilan berbasis vektor padat dan jarang. Pendekatan ini memungkinkan pencarian semantik yang memperhatikan kata kunci, di mana vektor jarang menyandikan bobot kata kunci bersama penyematan semantik padat.

ret = collection.query(
    vector=[0.1, 0.2, 0.3, 0.4],
    sparse_vector={1: 0.3, 20: 0.7},
    group_by_field='name',
)

Untuk detail tentang pencarian vektor semantik yang memperhatikan kata kunci, lihat Keyword-aware semantic vector search.

Parameter permintaan

Tentukan salah satu dari vector atau id.
ParameterTipeBawaanDeskripsi
group_by_fieldstrNoneRequired. Bidang yang digunakan untuk mengelompokkan hasil. Bidang bebas skema tidak didukung.
vectorOptional[Union[List[Union[int, float]], np.ndarray]]NoneVektor kueri.
idOptional[str]NoneKunci primer. Pencarian menggunakan vektor yang tersimpan untuk dokumen ini.
group_countint10Jumlah maksimum kelompok yang dikembalikan. Parameter ini bersifat best-effort. Secara umum, jumlah kelompok yang ditentukan dapat dikembalikan.
group_topkint10Jumlah hasil mirip yang dikembalikan per kelompok. Parameter ini bersifat best-effort dan memiliki prioritas lebih rendah daripada group_count.
filterOptional[str]NoneFilter kondisional menggunakan sintaksis klausa WHERE SQL. Lihat Conditional filtering.
include_vectorboolFalseMenentukan apakah data vektor disertakan dalam tanggapan.
partitionOptional[str]NonePartisi tempat pencarian dilakukan.
output_fieldsOptional[List[str]]NoneBidang yang dikembalikan. Secara bawaan mengembalikan semua bidang.
sparse_vectorOptional[Dict[int, float]]NoneVektor jarang untuk pengambilan yang memperhatikan kata kunci.
async_reqboolFalseMenentukan apakah permintaan dikirim secara asinkron.

Parameter respons

Mengembalikan objek DashVectorResponse. Untuk kode status, lihat Status codes.

ParameterTipeDeskripsiContoh
codeintKode status.0
messagestrPesan respons.success
request_idstrID permintaan.19215409-ea66-4db9-8764-26ce2eb5bb99
outputList[Group]Hasil pencarian yang dikelompokkan.

Batasan

  • group_by_field harus merupakan bidang yang didefinisikan dalam skema. Bidang bebas skema tidak didukung.

  • group_count dan group_topk adalah parameter best-effort. Jumlah kelompok atau hasil per kelompok yang sebenarnya dikembalikan mungkin lebih sedikit dari yang ditentukan.