התייחסות לסיוע וקטורי

בדף הזה מפורט מידע על כל הפונקציות הזמינות של העזרה בווקטורים, ועל הפרמטרים הנדרשים והאופציונליים שלהן.

vector_assist.define_spec

הפונקציה מגדירה מפרט וקטורי חדש, או מפרט וקטורי, ומחזירה המלצות שנדרשות כדי להגדיל את עומס העבודה של הווקטור. הפונקציה הזו משתמשת במפרטים שהמשתמשים סיפקו כדי ליצור את ההמלצות.

תפקיד

CREATE OR REPLACE FUNCTION vector_assist.define_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT,
    schema_name TEXT DEFAULT NULL,
    vector_column_name TEXT DEFAULT NULL,
    text_column_name TEXT DEFAULT NULL,
    vector_index_type TEXT DEFAULT NULL, -- Allowed: 'hnsw', 'ivfflat'
    embeddings_available BOOL DEFAULT NULL,
    embedding_model TEXT DEFAULT NULL,
    num_vectors INT DEFAULT NULL,
    dimensionality INT DEFAULT NULL,
    distance_func TEXT DEFAULT NULL, -- Allowed: 'cosine', 'ip', 'l2', 'l1'
    quantization TEXT DEFAULT NULL, -- Allowed: 'none', 'halfvec', 'bit'
    prefilter_column_names TEXT[] DEFAULT NULL,
    memory_budget_kb INT DEFAULT NULL, -- In KB
    target_recall FLOAT DEFAULT NULL,
    target_top_k INT DEFAULT NULL,
    tune_vector_index BOOL DEFAULT FALSE, -- Set to true if target_recall is set
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

פרמטרים

פרמטר חובה? תיאור
spec_id חובה (נוצר באופן אוטומטי) מזהה ייחודי של מפרט הווקטור שאתם מגדירים.
table_name חובה? שם הטבלה שבה יש להשתמש בהגדרת עומס העבודה של הווקטורים.
schema_name אופציונלי הסכימה שמכילה את הטבלה שתשמש לעומס העבודה של הווקטור. הסכימה מוסקת באופן אוטומטי על סמך נתיב החיפוש של הסכימה.
vector_column_name אופציונלי או חובה שם העמודה שמכילה את הטמעות הווקטורים.

העמודה הזו נדרשת אם משתמשים ביותר מעמודת וקטור אחת ולא מציינים את text_column_name. אם משתמשים רק בעמודת וקטור אחת, הפרמטר הזה הוא אופציונלי.
text_column_name אופציונלי או חובה שם העמודה של עמודת הטקסט. אם עומס העבודה של הווקטור דורש יצירת הטבעות מעמודת טקסט, הפרמטר הזה נדרש.

חובה לכלול את העמודה הזו אם הפרמטר vector_column_name הוא NULL ואין עמודות וקטוריות אחרות.

הפרמטר הזה משתמש בתוסף google_ml_integration כדי ליצור הטמעות מתוך עמודת הטקסט שצוינה.
vector_index_type אופציונלי סוג אינדקס הווקטורים. ערכים קבילים:
  • HNSW
  • IVFFlat
  • SCANN
embeddings_available אופציונלי ערך בוליאני שבודק אם קיימים הטמעות וקטוריות בטבלה שנבחרה. השדה הזה מוגדר ל-FALSE אם לא מזוהות עמודות וקטוריות והפרמטר text_column_name מוגדר.
embedding_model אופציונלי או חובה מזהה המודל מ-‎google_ml.models שבו יש להשתמש כדי ליצור את ההטמעות. השדה הזה הוא אופציונלי, אלא אם הפרמטר embeddings_available הוא FALSE או NULL.
num_vectors אופציונלי מספר הווקטורים בטבלה.
dismensionality אופציונלי הממד של הווקטורים הנתונים.
distance_func אופציונלי פונקציית המרחק שתשמש להשוואה בין וקטורים. ערכים קבילים כוללים cosine,‏ ip,‏ l2 או l1.
quantization אופציונלי הקוונטיזציה של אינדקסים של וקטורים. ערכים קבילים: none,‏ halfvec או bit.
prefilter_column_names אופציונלי יוצרת אינדקס לעמודה שצוינה לצורך סינון מראש. הפעולה הזו עשויה לשפר את הביצועים של שאילתות עם מסנן סלקטיביות גבוה בעמודה.
memory_budget_kb אופציונלי הזיכרון המקסימלי (ב-KB) ליצירת אינדקס.
target_recall אופציונלי ההחזרה של התוצאות הרלוונטיות לחיפושים של וקטורים רגילים.
target_top_k אופציונלי מספר הערכים התואמים המובילים שיש לאחזר לצורך חישוב ההחזרה. הערך הזה משמש אם מציינים את הפרמטר target_recall.
tune_vector_index אופציונלי מכוונן את מדדי הווקטור בעומס העבודה. אם האפשרות הזו מופעלת, התכונה 'סיוע וקטורי' מכוונת אוטומטית את אינדקס הווקטור או את שאילתת החיפוש באמצעות מפרט הווקטור, ומחשבת את הפרמטרים האופטימליים של מסד הנתונים והאינדקס. הערכים האפשריים הם TRUE או FALSE.

ערך מוחזר

מחזירה טבלה של המלצות שצריך להחיל כדי להגדיר את עומס העבודה של הווקטור המבוקש. כל שורה היא המלצה אחת שמכילה שאילתת SQL שאפשר להריץ והסבר מפורט למה כדאי ליישם את ההמלצה. אפשר ליישם את ההמלצה באמצעות הפונקציה apply_recommendation().

טבלת ההמלצות כוללת את העמודות הבאות:

שם העמודה סוג תיאור
recommendation_id טקסט המזהה של ההמלצה. ההמלצה מיושמת באמצעות המזהה הזה.
vector_spec_id טקסט המזהה של מפרט הווקטור שמשויך להמלצה.
table_name טקסט שם הטבלה שמשויכת להמלצה.
schema_name טקסט שם הסכימה שמכילה את הטבלה הנתונה.
query טקסט שאילתת SQL שניתן להריץ כדי להשיג את התוצאה של ההמלצה.
recommendation טקסט ההסבר להמלצה, כולל התוצאה הצפויה אחרי יישום ההמלצה. העמודה הזו מכילה גם את הסיבה וההסבר להמלצה. אפשר להשתמש בהקשר הזה כדי לשנות את השאילתה לפי הצורך וליצור מחדש המלצות.
applied בוליאני האם ההמלצה יושמה.
modified בוליאני מראה אם המשתמש שינה את ההמלצה.
created_at חותמת זמן עם אזור זמן השעה שבה נוצרה ההמלצה בפורמט timestamp with time zone. לדוגמה: 2024-07-18 09:00:00-08.

vector_assist.list_specs

מחזירה את מפרט הווקטור הנוכחי עבור טבלה ועמודה נתונות.

תפקיד

CREATE OR REPLACE FUNCTION vector_assist.list_specs(
  table_name      TEXT,
  column_name     TEXT DEFAULT NULL
)
RETURNS SETOF vector_assist.VECTOR_SPECS

פרמטרים

פרמטר חובה? תיאור
table_name חובה? שם הטבלה שלגביה מאחזרים את מפרט הווקטור.
column_name אופציונלי שם העמודה שלפיה רוצים לסנן את הטבלה לפני החזרת המפרט. אם מציינים את שם העמודה, מוחזרים מפרטים שמכילים שמות של עמודות טקסט או וקטור שתואמים לשם העמודה הזה.

ערך מוחזר

מחזירה טבלה של מפרטים עבור הטבלה הנתונה, ואפשר גם לציין שם עמודה.

vector_assist.modify_spec

משנה מפרט וקטורי קיים. כשמשנים את המפרט הווקטורי, ההמלצות המשויכות נוצרות מחדש על סמך המפרטים החדשים.

תפקיד

CREATE OR REPLACE FUNCTION vector_assist.modify_spec(
  spec_id                TEXT,
  table_name             TEXT DEFAULT NULL,
  schema_name            TEXT DEFAULT NULL,
  vector_column_name     TEXT DEFAULT NULL,
  text_column_name       TEXT DEFAULT NULL,
  vector_index_type      TEXT DEFAULT NULL,
  embeddings_available   BOOL DEFAULT NULL,
  num_vectors            INT DEFAULT NULL,
  dimensionality         INT DEFAULT NULL,
  embedding_model        TEXT DEFAULT NULL,
  prefilter_column_names TEXT[] DEFAULT NULL,
  distance_func          TEXT DEFAULT NULL,
  quantization           TEXT DEFAULT NULL,
  memory_budget_kb       INT DEFAULT NULL,
  target_recall          FLOAT DEFAULT NULL,
  target_top_k           INT DEFAULT NULL,
  tune_vector_index      BOOL DEFAULT NULL
)
RETURNS SETOF vector_assist.RECOMMENDATIONS

פרמטרים

פרמטר חובה? תיאור
spec_id חובה (נוצר באופן אוטומטי) מזהה ייחודי של מפרט הווקטור שאתם מגדירים.
table_name חובה? שם הטבלה שבה יש להשתמש בהגדרת עומס העבודה של הווקטורים.
schema_name אופציונלי הסכימה שמכילה את הטבלה שתשמש לעומס העבודה של הווקטור. הסכימה מוסקת באופן אוטומטי על סמך נתיב החיפוש של הסכימה.
vector_column_name אופציונלי או חובה שם העמודה שמכילה את הטמעות הווקטורים.

העמודה הזו נדרשת אם משתמשים ביותר מעמודת וקטור אחת ולא מציינים את text_column_name. אם משתמשים רק בעמודת וקטור אחת, הפרמטר הזה הוא אופציונלי.
text_column_name אופציונלי או חובה שם העמודה של עמודת הטקסט. אם עומס העבודה של הווקטור דורש יצירת הטבעות מעמודת טקסט, הפרמטר הזה נדרש.

חובה לכלול את העמודה הזו אם הפרמטר vector_column_name הוא NULL ואין עמודות וקטוריות אחרות.

הפרמטר הזה משתמש בתוסף google_ml_integration כדי ליצור הטמעות מתוך עמודת הטקסט שצוינה.
vector_index_type אופציונלי סוג אינדקס הווקטורים. ערכים קבילים:
  • HNSW
  • IVFFlat
  • SCANN
embeddings_available אופציונלי ערך בוליאני שבודק אם קיימים הטמעות וקטוריות בטבלה שנבחרה. השדה הזה מוגדר ל-FALSE אם לא מזוהות עמודות וקטוריות והפרמטר text_column_name מוגדר.
embedding_model אופציונלי או חובה מזהה המודל מ-‎google_ml.models שבו יש להשתמש כדי ליצור את ההטמעות. השדה הזה הוא אופציונלי, אלא אם הפרמטר embeddings_available הוא FALSE או NULL.
num_vectors אופציונלי מספר הווקטורים בטבלה.
dismensionality אופציונלי הממד של הווקטורים הנתונים.
distance_func אופציונלי פונקציית המרחק שתשמש להשוואה בין וקטורים. ערכים קבילים כוללים cosine,‏ ip,‏ l2 או l1.
quantization אופציונלי הקוונטיזציה של אינדקסים של וקטורים. ערכים קבילים: none,‏ halfvec או bit.
prefilter_column_names אופציונלי מזהה את העמודות שזמינות לסינון מראש בשאילתות של חיפוש וקטורי.
memory_budget_kb אופציונלי הזיכרון המקסימלי (ב-KB) ליצירת אינדקס.
target_recall אופציונלי ההחזרה של התוצאות הרלוונטיות לחיפושים של וקטורים רגילים.
target_top_k אופציונלי מספר הערכים התואמים המובילים שיש לאחזר לצורך חישוב ההחזרה. הערך הזה משמש אם מציינים את הפרמטר target_recall.
tune_vector_index אופציונלי מכוונן את מדדי הווקטור בעומס העבודה. אם האפשרות הזו מופעלת, התכונה 'סיוע וקטורי' מכוונת אוטומטית את אינדקס הווקטור או את שאילתת החיפוש באמצעות מפרט הווקטור, ומחשבת את הפרמטרים האופטימליים של מסד הנתונים והאינדקס. הערכים האפשריים הם TRUE או FALSE.

ערך מוחזר

הפונקציה מחזירה טבלה מעודכנת של המלצות שצריך להחיל כדי להגדיר את עומס העבודה של הווקטור המבוקש. כל שורה היא המלצה אחת שמכילה שאילתת SQL שאפשר להריץ והסבר מפורט למה כדאי ליישם את ההמלצה. אפשר ליישם את ההמלצה באמצעות הפונקציה apply_recommendation().

טבלת ההמלצות כוללת את העמודות הבאות:

שם העמודה סוג תיאור
recommendation_id טקסט המזהה של ההמלצה. ההמלצה מיושמת באמצעות המזהה הזה.
vector_spec_id טקסט המזהה של מפרט הווקטור שמשויך להמלצה.
table_name טקסט שם הטבלה שמשויכת להמלצה.
schema_name טקסט שם הסכימה שמכילה את הטבלה הנתונה.
query טקסט שאילתת SQL שניתן להריץ כדי להשיג את התוצאה של ההמלצה.
recommendation טקסט ההסבר להמלצה, כולל התוצאה הצפויה אחרי יישום ההמלצה. העמודה הזו מכילה גם את הסיבה וההסבר להמלצה. אפשר להשתמש בהקשר הזה כדי לשנות את השאילתה לפי הצורך וליצור מחדש המלצות.
applied בוליאני האם ההמלצה יושמה.
modified בוליאני מראה אם המשתמש שינה את ההמלצה.
created_at חותמת זמן עם אזור זמן השעה שבה ההמלצה נוצרה.

vector_assist.get_recommendations

הפונקציה מחזירה המלצות שמשויכות לווקטור ספציפי spec_id.

תפקיד

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

פרמטרים

פרמטר חובה? תיאור
spec_id חובה? מקבלים המלצות לגבי הווקטור שצוין spec_id.

ערך מוחזר

הפונקציה מחזירה טבלה של המלצות מבוקשות.

טבלת ההמלצות כוללת את העמודות הבאות:

שם העמודה סוג תיאור
recommendation_id טקסט המזהה של ההמלצה. ההמלצה מיושמת באמצעות המזהה הזה.
vector_spec_id טקסט המזהה של מפרט הווקטור שמשויך להמלצה.
table_name טקסט שם הטבלה שמשויכת להמלצה.
schema_name טקסט שם הסכימה שמכילה את הטבלה הנתונה.
query טקסט שאילתת SQL שניתן להריץ כדי להשיג את התוצאה של ההמלצה.
recommendation טקסט ההסבר להמלצה, כולל התוצאה הצפויה אחרי יישום ההמלצה. העמודה הזו מכילה גם את הסיבה וההסבר להמלצה. אפשר להשתמש בהקשר הזה כדי לשנות את השאילתה לפי הצורך וליצור מחדש המלצות.
applied בוליאני האם ההמלצה יושמה.
modified בוליאני מראה אם המשתמש שינה את ההמלצה.
created_at חותמת זמן עם אזור זמן השעה שבה ההמלצה נוצרה.

vector_assist.apply_recommendation

מיישמת המלצה אחת באמצעות recommendation_id.

תפקיד

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

פרמטרים

פרמטר חובה? תיאור
recommenation_id חובה? המזהה של המלצת הווקטור שרוצים להחיל.

ערך מוחזר

הפונקציה מחזירה ערך בוליאני שמאשר שהמלצה יושמה בהצלחה, ומעדכנת את vector_assist.RECOMMENDATIONS עמודת הטבלה applied לערך TRUE.

אם העזרה בווקטורים לא מצליחה להחיל את ההמלצה, תוצג הודעת שגיאה.

vector_assist.apply_spec

מיישם את כל ההמלצות שמשויכות לווקטור מסוים spec_id או לשם טבלה. הפונקציה הזו עוברת על כל ההמלצות ומפעילה את הפונקציה vector_assist.apply_recommendation על כל המלצה.

כדי להפעיל את הפונקציה, צריך לציין spec_id או table_name.

תפקיד

CREATE OR REPLACE FUNCTION vector_assist.apply_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL -- text_column_name or vector_column_name
)
RETURNS BOOLEAN;

פרמטרים

פרמטר חובה? תיאור
spec_id אופציונלי הפונקציה מחילה את כל ההמלצות על הווקטור הנתון spec_id.
table_name אופציונלי מחיל את כל ההמלצות על הטבלה הנתונה.
schema_name אופציונלי הסכימה שמכילה את הטבלה שצוינה.
column_name אופציונלי מזהה את text_column_name או את vector_column_name שבהם צריך להשתמש אם הטבלה מכילה כמה מפרטי וקטורים.

ערך מוחזר

הפונקציה מחזירה ערך בוליאני שמאשר שכל ההמלצות יושמו בהצלחה, ומגדירה את הערך בעמודה vector_assist.RECOMMENDATIONS בטבלה applied ל-TRUE עבור כל ההמלצות.

אם העזרה בווקטורים לא מצליחה להחיל את ההמלצה, תוצג הודעת שגיאה.

vector_assist.modify_recommendation

משנה את השאילתה להמלצה ספציפית ומגדיר את השדה modified בטבלה vector_assist.RECOMMENDATIONS להמלצה המשויכת לערך TRUE.

תפקיד

CREATE OR REPLACE FUNCTION vector_assist.modify_recommendation(
    recommendation_id TEXT,
    modified_query TEXT
)
RETURNS BOOLEAN;

פרמטרים

פרמטר חובה? תיאור
recommendation_id חובה? המזהה של ההמלצה שרוצים לשנות.
modified_query חובה? שאילתת SQL שמשתמש שינה בשביל ההמלצה.

ערך מוחזר

הפונקציה מחזירה ערך בוליאני שמאשר שההמלצה עודכנה בהצלחה ומגדירה את העמודה vector_assist.RECOMMENDATIONS בטבלה modified לערך TRUE.

אם העזרה בווקטור לא מצליחה לעדכן את ההמלצה, תוצג הודעת שגיאה.

vector_assist.generate_query

יצירת שאילתת חיפוש וקטורית שעברה אופטימיזציה על סמך מפרט הווקטור ופרמטרי החיפוש שהוגדרו. הפונקציה הזו עשויה לשנות את הערך של ef_search כדי לעמוד בדרישות של target_recall, אם זה רלוונטי.

תפקיד

CREATE OR REPLACE FUNCTION vector_assist.generate_query(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL, -- text_column_name or vector_column_name of the spec
    search_text TEXT DEFAULT NULL,
    search_vector VECTOR DEFAULT NULL, -- e.g. '[1.0,2.0,3.0]'::vector
   output_column_names TEXT[] DEFAULT NULL, -- Columns to retrieve, NULL for SELECT *
    top_k INT DEFAULT NULL,
    filter_expressions TEXT[] DEFAULT NULL,
    target_recall FLOAT DEFAULT NULL, -- Inherited from spec, can be overridden
    iterative_index_search BOOL DEFAULT NULL
)
RETURNS TEXT; -- Returns the text representing the search query

פרמטרים

פרמטר חובה? תיאור
spec_id אופציונלי מציינים את spec_id שעבורו רוצים ליצור את השאילתה.
table_name אופציונלי ההגדרה הזו מציינת את שם הטבלה ליצירת שאילתת החיפוש אם לא צוינה ההגדרה spec_id. אם טבלה מכילה כמה מפרטים, הפרמטר מחזיר שגיאה.
column_name אופציונלי מציינת את שם העמודה ליצירת שאילתת החיפוש אם לא צוינה ההגדרה spec_id. אם העמודה מכילה כמה מפרטים, הפרמטר מחזיר שגיאה. הערך של column_name יכול להיות text_column_name או vector_column_name.
output_column_name אופציונלי שמות העמודות שרוצים לאחזר בשאילתת הפלט. כדי לאחזר את כל העמודות, מגדירים את הפרמטר הזה לערך NULL.
search_text אופציונלי טקסט החיפוש ליצירת הטמעות. נדרש הפרמטר embedding_model במפרט הווקטור. הווקטור נוצר באמצעות המודל מהמפרט. אפשר להגדיר רק את הפרמטר search_text או את הפרמטר search_vector.
search_vector אופציונלי הווקטור של שאילתת החיפוש. אפשר להגדיר רק את הפרמטר search_text או את הפרמטר search_vector
top_k אופציונלי מספר השכנים הקרובים שיש להחזיר.
filter_expressions אופציונלי ביטויי הסינון להחלה בשאילתת החיפוש. אפשר להחיל את המסננים על שדות בטבלה, כמו מחיר < 100.
iterative_index_search אופציונלי הגדרה של ביצוע חיפוש אינדקס איטרטיבי לשאילתות מסוננות.הפרמטר הזה מבטל את ההגדרות במפרט הווקטור.
target_recall אופציונלי ההחזרה של התוצאות הרלוונטיות רק לשאילתת החיפוש. הפרמטר הזה מבטל את ההגדרות במפרט הווקטור ומכוונן את ef_search.

ערך מוחזר

הפונקציה מחזירה טקסט שמכיל את שאילתת החיפוש הווקטורי לפרמטרים שצוינו. אפשר להריץ את השאילתה הזו או לשמור אותה להרצה מאוחר יותר.

vector_assist.evaluate_query_recall

הפונקציה מעריכה את ההחזרה של אינדקס הווקטור עבור שאילתה נתונה. הפונקציה הזו משתמשת בהגדרות של מסד הנתונים והאינדקס במחרוזת JSON כקלט.

תפקיד

CREATE OR REPLACE FUNCTION vector_assist.evaluate_query_recall(
  IN ann_query text,
  IN vector_search_configurations json DEFAULT NULL,
  OUT recall float,
  OUT ann_execution_time float,
  OUT ground_truth_execution_time float,
  OUT index_type text)
RETURNS RECORD

פרמטרים

פרמטר חובה? תיאור
ann_query חובה? שאילתת ה-SQL שצריך להעריך את ההחזרה שלה. השאילתה הזו צריכה להיות שאילתת pgvector ANN.
vector_search_configurations אופציונלי ההגדרות שאפשר להגדיר לשאילתת ANN. הפרמטר הזה חייב להיות בפורמט JSON.

ערך מוחזר

הפונקציה מחזירה טבלה שמעריכה את הזיכרון של אינדקס הווקטור לשאילתה הנתונה.

הטבלה מכילה את העמודות הבאות:

שם העמודה סוג תיאור
recall Float אחוז הווקטורים שהאינדקס מחזיר, שהם השכנים הקרובים האמיתיים. המדד הזה משמש לכימות של איכות החיפוש. הפונקציה הזו מאפשרת לכם לשנות את הפרמטרים כדי לקבל את התוצאות הצפויות של שאילתת וקטור.
ann_execution_time Float הזמן שלוקח להריץ שאילתת וקטור באמצעות סריקות אינדקס.
ground_truth_execution_time Float הזמן שלוקח להריץ את השאילתה באמצעות סריקה רציפה.

דוגמה

בדוגמה הבאה מבוצעת הערכה של ה-recall לאינדקס HNSW, ומוגדר ערך חדש לפרמטר ההגדרה HNSW.ef_search:

SELECT * FROM vector_assist.evaluate_query_recall(
  ann_query => 'SELECT id FROM items ORDER BY embedding <=> ''[1,2,3]'' LIMIT 10',
  vector_search_configurations => '{"hnsw.ef_search": 30}'
);