Periplus

Periplus

คำเตือน: Periplus อยู่ในอัลฟ่า

Periplus อยู่ในอัลฟ่าและยังไม่พร้อมการผลิต โครงการอยู่ระหว่างการพัฒนาที่ใช้งานอยู่และยังไม่แนะนำให้ใช้ในระบบการผลิต

การแนะนำ

Periplus เป็นแคชฐานข้อมูลเวกเตอร์ในโอเพ่นซอร์สโอเพ่นซอร์สที่สร้างขึ้นบนไลบรารีการค้นหาเวกเตอร์ที่คล้ายคลึงกันของเมตา โครงการสามารถคิดได้ดีที่สุดว่า "Redis สำหรับฐานข้อมูลเวกเตอร์" มันถูกออกแบบมาเพื่อจัดเก็บชุดย่อยที่อัปเดตแบบไดนามิกของคอลเลกชันเวกเตอร์ขนาดใหญ่ทั้งหมดในหน่วยความจำในขณะที่ให้บริการแบบสอบถามโดยไม่ต้องโต้ตอบกับโหนดอื่น ๆ ในเวลาค้นหา เมื่อ Periplus ได้รับการสืบค้นก่อนจะประเมินว่ามีส่วนที่เกี่ยวข้องของดัชนีในที่พักอาศัยหรือไม่ ถ้าเป็นเช่นนั้นมันจะแก้ไขการสืบค้นด้วยการตอบกลับที่เหมาะสม หากไม่เป็นเช่นนั้นมันจะส่งคืนแคชพลาดและออกจาก querier เพื่อดึงข้อมูลจากฐานข้อมูล Periplus ไม่ได้ออกแบบมาเพื่อทำงานแยก แต่มันหมายถึงการสร้างชั้นแคชแบบแยกส่วนและยืดหยุ่นสำหรับฐานข้อมูลเวกเตอร์แยกต่างหากซึ่งเป็นชั้นการคงอยู่ จุดประสงค์ของสิ่งนี้คือเพื่อให้สามารถใช้เวลาแฝงที่ต่ำกว่าและปรับขนาดแนวนอนได้ง่ายเพื่อเพิ่มปริมาณงาน สำหรับคำอธิบายโดยละเอียดเพิ่มเติมเกี่ยวกับแรงบันดาลใจเบื้องหลัง Periplus และวิธีการทำงานคุณสามารถอ่านบล็อกประกาศ: แนะนำ Periplus: วิธีการใหม่ในการแคชฐานข้อมูล Vector

มันทำงานอย่างไร

Periplus ใช้ดัชนีไฟล์แบบกลับด้าน (IVF) เป็นพื้นฐานสำหรับการจัดการแคช ดัชนีไฟล์แบบกลับด้านพาร์ติชันพื้นที่เวกเตอร์เป็นเซลล์ที่ต่อเนื่องกันที่กำหนดโดยชุดของเวกเตอร์เซนทรอยด์ที่แต่ละเซลล์ถูกกำหนดให้เป็นภูมิภาคที่อยู่ใกล้กับเซนทรอยด์มากกว่าเซนทรอยด์อื่น ๆ แบบสอบถามจะได้รับการแก้ไขโดยการคำนวณระยะทางก่อนจากเวกเตอร์แบบสอบถามไปยังชุดของเซนทรอยด์จากนั้นค้นหาเฉพาะเซลล์ที่กำหนดโดย N_PROBE (การค้นหา hyperparameter) centroids ที่ใกล้เคียงที่สุด Periplus ใช้ประโยชน์จากสิ่งนี้โดยการรักษาชุดย่อยของเซลล์เหล่านี้ในที่อยู่อาศัยในเวลาใดก็ตามและแก้ไขเฉพาะการสอบถามที่เกี่ยวข้องกับชุดย่อยนั้นในขณะที่ปฏิเสธเซลล์ที่ไม่ได้พลาดแคช Periplus โหลดและขับไล่เซลล์ IVF ทั้งหมดในเวลาเดียวกันเพื่อรักษาความสมบูรณ์ของดัชนีและตรวจสอบให้แน่ใจว่าการเรียกคืนที่เทียบเท่า (บนแคชฮิต) ไปยังดัชนี IVF มาตรฐาน เซลล์ IVF จะถูกโหลดโดยการสืบค้นฐานข้อมูลเวกเตอร์ผ่านพร็อกซีที่มีรายการ ID ของเวกเตอร์ซึ่ง Periplus เก็บรักษาไว้เพื่อติดตามว่าเวกเตอร์ใดครอบครองเซลล์ใด การดำเนินการเหล่านี้สามารถเรียกใช้โดยผู้ใช้โดยใช้คำ สั่งโหลด ค้นหา และ ขับไล่ คำสั่ง สำหรับรายละเอียดดูส่วนคำสั่ง Periplus ด้านล่าง

วิ่ง periplus

Periplus สามารถเรียกใช้เป็นคอนเทนเนอร์ Docker หรือสามารถสร้างได้จากแหล่งที่มาและเรียกใช้เป็นปฏิบัติการ ปัจจุบันไม่มีไบนารีอย่างเป็นทางการ การรัน Periplus เป็นคอนเทนเนอร์เป็นวิธีที่แนะนำ แต่ทั้งคู่เป็นตัวเลือกที่ทำงานได้

- รัน periplus เป็นคอนเทนเนอร์

ปัจจุบันอิมเมจ Docker รองรับสถาปัตยกรรม AMD64 เท่านั้น ข้อ จำกัด นี้เกิดจากภาพพื้นฐาน แต่จะได้รับการสนับสนุนสถาปัตยกรรมมากขึ้นในอนาคตอันใกล้ มี 2 ​​วิธีในการเรียกใช้ Periplus เป็นคอนเทนเนอร์: ดาวน์โหลดภาพ Docker อย่างเป็นทางการจาก DockerHub (แนะนำ) หรือสร้างภาพด้วยตัวเอง ขั้นตอนแรกในทั้งสองกรณีคือการติดตั้ง Docker หากคุณยังไม่ได้ทำ คำแนะนำในการทำเช่นนั้นสามารถพบได้ที่นี่

ใช้ภาพอย่างเป็นทางการ

1. ดาวน์โหลดภาพโดยรัน: docker image pull qdl123/periplus:latest
2. เรียกใช้คอนเทนเนอร์: docker run -p 3000:3000 qdl123/periplus:latest

การสร้างภาพ

1. โคลนที่เก็บ: git clone https://github.com/QDL123/Periplus.git
2. CD ไปยังรูทที่เก็บ: cd <path-to-periplus-repo>/Periplus
3. สร้างภาพ: docker build -t periplus-image .
4. เรียกใช้คอนเทนเนอร์: docker run -p 3000:3000 periplus-image .

การสร้าง periplus จากแหล่งที่มา

Periplus ใช้ CMAKE สำหรับระบบสร้าง คาดว่าการพึ่งพาทั้งหมดจะติดตั้งไบนารีไว้ล่วงหน้าผ่าน Homebrew Homebrew ได้รับการสนับสนุนจาก MacOS, Ubuntu และ WSL หากคุณอยู่ใน Windows Periplus ถูกสร้างขึ้นบน MacOS/ARM64 และ Ubuntu/AMD64 ระบบปฏิบัติการและสถาปัตยกรรมอื่น ๆ ทั้งหมดยังไม่ได้ทดสอบ ในการสร้าง periplus จากแหล่งที่มาให้ทำตามขั้นตอนต่อไปนี้:

1. ติดตั้ง Homebrew: เยี่ยมชมเว็บไซต์ Homebrew อย่างเป็นทางการที่นี่เพื่อขอคำแนะนำในการติดตั้ง
2. ติดตั้งการพึ่งพาของ Periplus หากต้องการติดตั้งทั้งหมดในครั้งเดียว Run: brew install faiss curl cpr rapidjson libomp catch2 cmake
3. โคลนที่เก็บ: git clone https://github.com/QDL123/Periplus.git
4. CD ไปยังรูทที่เก็บ: cd <path-to-periplus-repo>/Periplus
5. สร้าง makefile: cmake -S . -B build
6. รวบรวมการดำเนินการ: cmake --build build
7. เรียกใช้ periplus (ฟังพอร์ต 3000): ./build/periplus -p 3000

ใช้ periplus

ระบบใด ๆ ที่ใช้ periplus จะประกอบด้วย 4 ส่วนประกอบ: ฐานข้อมูลเวกเตอร์, พร็อกซีฐานข้อมูลซึ่งอนุญาตให้ Periplus โหลดข้อมูลจากฐานข้อมูลอินสแตนซ์ periplus และแอปพลิเคชันไคลเอนต์

ตัวอย่างสถาปัตยกรรมของแอปพลิเคชันโดยใช้ Periplus

ฐานข้อมูลเวกเตอร์

ฐานข้อมูลเวกเตอร์ใด ๆ ที่อนุญาตให้ค้นหาข้อมูลโดยตัวระบุที่ไม่ซ้ำกัน (แทบทั้งหมด) จะทำงานได้ Periplus ได้รับการออกแบบให้มีประโยชน์มากที่สุดเมื่อทำงานกับคอลเลคชั่นเวกเตอร์ขนาดใหญ่ (พันล้านระดับ) ซึ่งดัชนีจะต้องอาศัยอยู่ในระบบไฟล์เมื่อเทียบกับ RAM แม้ว่าจะไม่ใช่ข้อกำหนดก็ตาม

พร็อกซีฐานข้อมูลเวกเตอร์

จุดประสงค์ของพร็อกซีฐานข้อมูลเวกเตอร์คือการจัดเตรียมอินเทอร์เฟซที่สอดคล้องกันสำหรับ Periplus เพื่อโต้ตอบกับฐานข้อมูลเวกเตอร์ผ่าน พร็อกซีจะต้องใช้อินเทอร์เฟซ REST ซึ่งยอมรับคำขอโพสต์ของแบบฟอร์มต่อไปนี้:

URL: นี่คือความยืดหยุ่นและสามารถระบุได้โดยไคลเอนต์ Periplus

ส่วนหัว: "Content-Type": "application/json

ร่างกาย:

{
    "ids" : [ " id-1 " , " id-2 " , " id-3 " ]
}

การตอบสนอง:

{
    "results" : [
        {
            "id" : " String " ,
            "embedding" : [ 0.1 , 0.2 , 0.3 ],
            "document" : " String " ,
            "metdata" : " String "
        }
    ]
}

เพื่อให้การใช้งานจุดสิ้นสุดนี้ง่ายขึ้นคุณสามารถใช้แพ็คเกจ Periplus-Proxy Python ซึ่งใช้ fastapi เพื่อตั้งค่าทุกอย่าง ผู้ใช้ทั้งหมดต้องทำคือใช้ฟังก์ชั่นต่อไปนี้และส่งผ่านเป็นอาร์กิวเมนต์:

async def fetch_ids(request: Query) -> QueryResult

สำหรับรายละเอียดเกี่ยวกับวิธีการทำเช่นนี้คุณสามารถตรวจสอบแพ็คเกจ periplus-proxy readme.md

Periplus

ทำตามคำแนะนำด้านบนเพื่อเริ่มต้นอินสแตนซ์ periplus

แอปพลิเคชันไคลเอนต์

หากต้องการโต้ตอบกับอินสแตนซ์ Periplus ของคุณให้ใช้ไลบรารีไคลเอนต์ Periplus ปัจจุบันรองรับ Python เท่านั้น สำหรับรายละเอียดเกี่ยวกับไลบรารีไคลเอนต์คุณสามารถดู readme.md

คำสั่ง periplus

1. เริ่มต้น : นี่คือคำสั่งการตั้งค่าสำหรับ periplus จะต้องมีการเรียกก่อนคำสั่งอื่น ๆ และการเริ่ม ต้นการเริ่มต้น ใด ๆ ที่ตามมาจะล้างข้อมูลทั้งหมดและรีเซ็ตอินสแตนซ์ periplus มีอาร์กิวเมนต์ที่จำเป็น 2 ข้อ: D (มิติของการรวบรวมเวกเตอร์) และ DB_URL (URL ของจุดสิ้นสุดพร็อกซีฐานข้อมูลที่ใช้ในการโหลดข้อมูล) นอกจากนี้ยังมีอาร์กิวเมนต์วัตถุตัวเลือกที่เป็นตัวเลือกที่มี 2 ตัวเลือกที่มีอยู่: Ntotal และ use_flat ครั้งแรก Ntotal คือการประเมินจำนวนเวกเตอร์ทั้งหมดในคอลเลกชัน สิ่งนี้ใช้เพื่อเพิ่มประสิทธิภาพจำนวนเซลล์ IVF ที่จะใช้ หากไม่ได้ระบุ Periplus จะเลือกพื้นกลางซึ่งอาจนำไปสู่ประสิทธิภาพที่ไม่ดี ประการที่สอง use_flat เป็นบูลีนที่สั่งให้ Periplus ใช้ดัชนีแบนแทนการใช้ปริมาณผลิตภัณฑ์ใด ๆ (PQ) โดยค่าเริ่มต้นค่านี้เป็นเท็จซึ่งในกรณีนี้การหาปริมาณผลิตภัณฑ์จะถูกนำไปใช้หากเวกเตอร์มีขนาดใหญ่พอและแบ่งออกเป็น subvector ได้ง่าย หากตั้งค่าเป็นจริงจะใช้ดัชนีการทำเด็กหลอดแก้วแบบแบนแทน
2. รถไฟ : คำสั่งนี้ตั้งค่าตำแหน่งของเซนทรอยด์ในดัชนีการทำเด็กหลอดแก้วที่เป็นพื้นฐานของแคช เมื่อตั้งตำแหน่งเซนทรอยด์แล้วจะไม่สามารถรีเซ็ตได้โดยไม่ต้องเช็ดแคชอย่างสมบูรณ์ ต้องใช้รายการของเวกเตอร์ฝังตัวเป็นอาร์กิวเมนต์ซึ่งควรเป็นตัวอย่างตัวแทนของคอลเลกชันเวกเตอร์ของคุณ ขอแนะนำให้ใช้มากถึง 10% ของคอลเลกชันทั้งหมดของคุณ แต่น้อยกว่านั้นก็โอเคสำหรับชุดข้อมูลขนาดใหญ่ที่ 10% จะครอบงำอินสแตนซ์ Periplus
3. เพิ่ม : คำสั่งนี้ทำให้ Periplus ตระหนักถึงข้อมูลโดยไม่ต้องเติมแคชจริง ๆ เพื่อให้สามารถโหลดได้ในภายหลังจากฐานข้อมูล เวกเตอร์ใด ๆ ที่ periplus ควรจะสามารถโหลดได้ก่อนจะต้องลงทะเบียนผ่านคำสั่ง ADD คำสั่งใช้ ID อาร์กิวเมนต์สองรายการและการฝังตัวซึ่งเป็นรายการที่มีความยาวเท่ากันกับ ID เวกเตอร์และการฝังเวกเตอร์ที่สอดคล้องกัน
4. โหลด : คำสั่งนี้สั่งให้ Periplus โหลดเซลล์ IVF (ดูวิธีการทำงานเพื่อดูรายละเอียด) จากฐานข้อมูล มันมีอาร์กิวเมนต์ที่จำเป็นอย่างหนึ่งเวกเตอร์บอกว่าเซลล์ใดที่จะกำหนดเป้าหมายและวัตถุตัวเลือกที่เป็นตัวเลือกที่มีตัวเลือกหนึ่งตัวเลือก n_load ซึ่งบอกว่ามีจำนวนเซลล์จำนวนมากที่จะโหลด Periplus จะโหลดเซลล์ N_Load ที่ใกล้ที่สุดไปยังเวกเตอร์จากฐานข้อมูล (N_Load ค่าเริ่มต้นเป็น 1 หากไม่ได้ระบุ) สิ่งนี้รับประกันได้ว่าคำสั่ง การค้นหา ที่ตามมาที่มีเวกเตอร์เดียวกันจะให้แคชตี (สมมติว่าเซลล์ไม่ได้ถูกขับออกมาก่อนและอาร์กิวเมนต์ N_Load ตรงกับอาร์กิวเมนต์ n_probe ที่ให้ไว้ในการค้นหา)
5. ค้นหา : คำสั่งนี้เรียกใช้ชุดของการสืบค้นกับข้อมูลที่เก็บไว้ใน Periplus ต้องใช้อาร์กิวเมนต์ที่จำเป็น 2 ข้อ: K ซึ่งระบุจำนวนเพื่อนบ้านที่ใกล้ที่สุดในการส่งคืนและ XQ ซึ่งเป็นรายการของเวกเตอร์แบบสอบถาม เป็นทางเลือกใช้วัตถุตัวเลือกที่มีสองตัวเลือกที่มีอยู่: n_probe และ require_all ครั้งแรกระบุจำนวนเซลล์ IVF ในการค้นหา ค่าที่ใหญ่กว่าส่งผลให้เกิดความหน่วงแฝงที่เพิ่มขึ้น แต่ยังเพิ่มการเรียกคืน (และอัตราการตีแคชที่ต่ำกว่าเมื่อใช้ require_all ) ค่าเริ่มต้นคือ 1 ถ้าไม่ระบุ ตัวเลือกที่สอง quire_all เป็นบูลีนที่กำหนดพฤติกรรมการตี/พลาดแคช หากตั้งค่าเป็นจริงเซลล์ที่ใกล้ที่สุด N_PROBE ทั้งหมดจะต้องอยู่ในที่พักอาศัยเพื่อให้แบบสอบถามเป็นแคชตี หากเท็จมีเพียงเซลล์ IVF ที่ใกล้ที่สุดเท่านั้นที่จะต้องอยู่ในที่พักอาศัยสำหรับการสืบค้นที่จะเป็นแคชที่ได้รับการโจมตีและ Periplus จะค้นหาเซลล์ IVF ที่เคยอยู่ในที่อยู่อาศัยจนถึงเซลล์ IVF ที่ใกล้เคียงที่สุด N_PROBE ค่าเริ่มต้นเป็นจริง คำสั่ง การค้นหา ส่งคืนรายการรายการของ tuples เอกสารที่แต่ละรายการสอดคล้องกับผลลัพธ์ K สำหรับเวกเตอร์แบบสอบถามที่สอดคล้องกันที่ให้ไว้ที่ดัชนีนั้น Cache Misses จะมีรายการความยาว 0. ในบางกรณีที่หายากหากความยาวคือ> 0 และ <k ที่บ่งชี้ว่าจำนวนเวกเตอร์ทั้งหมดในเซลล์ N_Probe ที่ใกล้ที่สุดคือ <k แต่ละเอกสาร Tuple มี 4 ฟิลด์: ID, EMBEDDING, METADATA และเอกสารซึ่งจะสอดคล้องกับค่าที่จัดทำโดยพร็อกซีฐานข้อมูลเมื่อโหลดข้อมูล
6. Evict : คำสั่งนี้ทำงานเหมือนกับ โหลด ยกเว้นว่าจะขับไล่เซลล์ IVF (S) หากมีอยู่จาก Periplus แทนที่จะโหลด มันมี arugment ที่จำเป็นอย่างหนึ่งเวกเตอร์บอกว่าเซลล์ใดที่จะกำหนดเป้าหมายและวัตถุทางเลือกที่มีตัวเลือกที่มีตัวเลือกเดียว n_evict whch บอกว่ามีกี่เซลล์ที่จะขับไล่ Periplus จะขับไล่เซลล์ที่สอดคล้องกับ centroids N_EVICT ที่ใกล้ที่สุดไปยังเวกเตอร์จาก Periplus (ค่าเริ่มต้น N_EVICT ถึง 1 ที่ไม่ได้ระบุ)

ตัวอย่าง

 from periplus_client import Periplus

# host, port
client = Periplus ( "localhost" , 13 )

# vector dimensionality, database proxy url, options: (nTotal)
await client . initialize ( d = d , db_url = url , options = { "nTotal" : 50000 })

training_data = [[ 0.43456 , ..., 0.38759 ], ...]
await client . train ( training_data )

ids = [ "0" , ..., "n" ]
embeddings = [[ 0.43456 , ..., 0.38759 ], ...]
await client . add ( ids = ids , embeddings = embeddings )

load_options = { "n_load" : 2 }
# query_vector, optional: options object
await client . load ([ embeddings [ 0 ]] load_options )

# k, query_vector
response = await client . search ( 5 , [ embeddings [ 0 ]])
print ( response )
'''
[ // Results for each of the n query vectors in xq
    [ // K nearest neighbors to this corresponding index in the xq list
        (
            id="n",
            embedding=[0.43456, ..., 0.38759],
            document="",
            metadata="{}"
        ),
        ...
    ],
    ...
]
'''

# query_vector
await client . evict ( embeddings [ 0 ])

การเปรียบเทียบ

เร็วๆ นี้!

การบริจาค

เรายินดีต้อนรับการมีส่วนร่วมใน Periplus! หากต้องการเรียนรู้วิธีเริ่มต้นดูคู่มือการบริจาค

ใบอนุญาต

โครงการนี้ได้รับใบอนุญาตภายใต้ใบอนุญาต MIT - ดูไฟล์ใบอนุญาตสำหรับรายละเอียด