יצירת סוכן לחיפוש נתונים

סוכן הגילוי של Knowledge Catalog הוא עוזר מבוסס-AI שמשפר את הרלוונטיות של תוצאות החיפוש לשאילתות מורכבות בשפה טבעית, על סמך יכולות החיפוש של Knowledge Catalog. הוא מספק תוצאות מדויקות יותר מ-Knowledge Catalog Search API הרגיל, כי הוא משפר את ההבנה של השאילתות ואת הניסוח שלהן. היכולת הזו חשובה במיוחד כשמדובר בשאילתות מורכבות או ארוכות.

תרחישים לדוגמה

סוכן הגילוי מספק ממשק צ'אט עם AI עשיר בתרחישים כמו:

  • כוונות ומגבלות מורכבות או משולבות: טיפול בבקשות חיפוש עם כמה קריטריונים, כמו חיפוש מערכי נתונים ב-us-central1 אבל לא כולל משאבים ב-BigQuery.
  • חיפוש שמתמקד בעסק: גילוי נכסי נתונים על סמך כוונת המשתמש וההקשר העסקי, ולא על סמך התאמה למונחים טכניים מדויקים.
  • חיפוש רב-שלבי: צמצום התוצאות באמצעות שיחה כדי לדייק את החיפוש.

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

איך זה עובד

סוכן הגילוי מבצע את השלבים הבאים כדי להגיב לשאילתת חיפוש:

  1. מנתח את הקלט כדי להבין את הכוונה של השאילתה, יוצר כמה וריאציות של חיפוש וממפה מונחים למסנני מטא-נתונים.
  2. חיפוש משאבים באמצעות החיפוש הסמנטי של Knowledge Catalog.
  3. דירוג התוצאות הממוזגות לפי רלוונטיות.

בתרשים הבא מפורט התהליך:

תהליך של סוכן Discovery לבקשות חיפוש.
נתיב העיבוד של בקשות חיפוש בסוכן הגילוי.

הסוכן מסתמך על Knowledge Catalog Search API כדי לאחזרGoogle Cloud משאבים רלוונטיים. קטע הקוד הבא מראה איך הסוכן קורא לחיפוש סמנטי ב-Knowledge Catalog:


      # Configure the request parameters for the
      # call to Knowledge Catalog Semantic Search API.
      endpoint = "dataplex.googleapis.com"

      client = dataplex_v1.CatalogServiceClient(
          client_options={"api_endpoint": endpoint}
      )

      location = "global"
      consumer_project_id = "my-gcp-project"
      parent_name = f"projects/{consumer_project_id}/locations/{location}"

      # Call Knowledge Catalog Semantic Search API.
      response = client.search_entries(
          request={
              "name": parent_name,
              "query": query,
              "page_size": 50,
              "semantic_search": True,
          }
      )

      # Call Knowledge Catalog LookupContext for each search result
      # to retrieve rich, LLM-ready metadata.
      entries = []
      for result in response.results:
          entry_name = result.dataplex_entry.name
          
          # Prepare the LookupContext request for the specific resource
          lookup_request = {
              "name": parent_name,
              "resources": [entry_name]
          }
          
          # Call the LookupContext API
          lookup_response = client.lookup_context(request=lookup_request)
          
          # Extract the rich context YAML to share with the agent
          entries.append({
              "entry_name": entry_name,
              "context": lookup_response.context
          })

      return {"results": entries}

לפני שמתחילים

כדי להריץ את סוכן הגילוי של Knowledge Catalog, צריך לוודא שאתם עומדים בדרישות הבאות:

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לשימוש בסוכן הגילוי, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים ב Google Cloud פרויקט iam.gserviceaccount.com:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

ההרשאות הנדרשות

כדי להשתמש בסוכן הגילוי, נדרשות ההרשאות הבאות:

  • dataplex.projects.search
  • aiplatform.endpoints.predict
  • serviceusage.services.use

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

הפעלת ממשקי ה-API

כדי להשתמש בסוכן הגילוי של Knowledge Catalog, צריך להפעיל את ממשקי ה-API הבאים בפרויקט: Knowledge Catalog API,‏ Vertex AI API ו-Service Usage API.

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

הפעלת ממשקי ה-API

הגדרת הסביבה

כדי להגדיר את סביבת הפיתוח של סוכן ה-Discovery:

  1. משכפלים את מאגר dataplex-labs.

    git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git

  2. עוברים לספריית הסוכן:

    cd dataplex-labs/knowledge_catalog_discovery_agent

  3. יוצרים ומפעילים סביבה וירטואלית של Python, ואז מתקינים את התלות שמופיעה בקובץ requirements.txt:

    • ‫google-adk (ערכה לפיתוח סוכנים)
    • ‫google-cloud-dataplex (Knowledge Catalog Python Client)
    • google-api-core
      python3 -m venv /tmp/kcsearch

  source /tmp/kcsearch/bin/activate

  pip3 install -r requirements.txt

  4. מגדירים את משתני הסביבה באמצעות הפקודה הבאה:

    
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID במזהה הפרויקט

הפעלת סוכן הגילוי כסוכן הבסיסי

כדי להריץ את סוכן הגילוי ישירות כסוכן הבסיס:

  1. בקובץ agent.py שנמצא בתיקייה knowledge_catalog_discovery_agent משנים את השם של המשתנה discovery_agent ל-root_agent.

  2. מריצים את הסוכן באמצעות הפקודה adk run:

    adk run path/to/agent/parent/folder

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫path/to/agent/parent/folder עם ספריית ההורה שמכילה את התיקייה עם הסוכן. לדוגמה, אם הסוכן נמצא ב-knowledge_catalog_discovery_agent/, מריצים את adk run מהספרייה agents/.

הפעלת סוכן הגילוי ככלי של סוכן

כדי לשלב את סוכן הגילוי בסוכן מותאם אישית גדול יותר, כמו my_custom_agent, צריך לבצע את הפעולות הבאות:

  1. מגדירים את מבנה הפרויקט כך שיכיל את מודול הסוכן לגילוי:

    my_custom_agent/
├── agent.py
└── knowledge_catalog_discovery_agent/
    ├── SKILL.md
    ├── agent.py
    ├── tools.py
    └── utils.py

  2. בקובץ agent.py של הסוכן המותאם אישית, מייבאים את סוכן הגילוי ומשתמשים בו ככלי של הסוכן. דוגמה:

    root_agent = llm_agent.Agent(
    model=google_llm.Gemini(model=GEMINI_MODEL),
    name="my_custom_agent",
    instruction=(
        "You are a Custom Agent. Your goal is to help users understand"
        " their data landscape, evaluate data assets, and derive insights"
        " from available resources. **IMPORTANT**: You should use the"
        " `knowledge_catalog_discovery_agent` to search for and discover"
        " data assets. For best results, pass in the Natural Language user'"
        " query as is to the `knowledge_catalog_discovery_agent`. Once assets"
        " are found, you should analyze their metadata, compare them, and"
        " provide recommendations or summaries to the user to help them make"
        " decisions. Focus on general metadata summary and comparison."
    ),
    tools=[
        agent_tool.AgentTool(discovery_agent),
    ],
)

  3. מריצים את הסוכן באמצעות הפקודה adk run:

    adk run path/to/agent/parent/folder

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫path/to/agent/parent/folder עם ספריית האם שמכילה את התיקייה my_custom_agent/. לדוגמה, אם הסוכן נמצא ב-agents/my_custom_agent/, מריצים את הפקודה adk run מהספרייה agents/.

המאמרים הבאים