跳至主要内容

REFERENCE

開發者參考

認證、API、SDK、Flow Agent 處理節點與參數取值的完整參考。

LLM Query Database

把自然語言問題交給模型產生 SQL 並執行，結果與 SQL 一併寫進變數。

LLM Query Database 是用於把自然語言問題轉換成 SQL 並執行的 processor，型別代號為 llm-query-database。

  1. 基本用法​

    執行時會將設定的自然語言問題交給指定的語言模型，模型依據語意模型（Semantic Layer）的結構產生對應的 SQL，執行後把查詢結果與該段 SQL 一併寫入指定變數，供後續 processor 使用。

    它和 SQL processor 的差別在誰來寫 SQL。SQL processor 需要事先寫好語句，適合查詢條件固定的情況；LLM Query Database 由模型現場產生語句，適合問題來自使用者、事前無法窮舉的情況。

    和 LLM Completion 掛載語意模型的做法相比，這個 processor 的範圍更窄：它只做一次「問題轉 SQL 再執行」，不會進行多輪推理或呼叫其他工具，因此結果比較可預期。

    這個 processor 只能透過 Workflow CRD 設定

    Odin 的 Flow Agent 視覺編輯器目前沒有提供 llm-query-database 節點，它不會出現在畫布的節點選單中。要使用它必須直接撰寫 Workflow CRD。

    Workflow.spec.processors[].type 的合法值由 CRD 定義，llm-query-database 是其中之一。

  2. 設定方式​

    在 Workflow CRD 的 spec.processors 中宣告：

    apiVersion: asgard-ai.com/v1alpha1
    kind: Workflow
    metadata:
      name: wf-sales-question
    spec:
      variables: []
      entries:
        - name: entry-main
          handlingProcessor: proc-ask
      exits: []
      processors:
        - name: proc-ask
          type: llm-query-database
          labels:
            display_name: 自然語言查詢
          configs:
            - name: semanticLayer
              value: sl-retail-pos
            - name: query
              expression: prevMessage
            - name: resultField
              value: queryResult
            - name: completionModel
              value: cm-builtin-balanced
            - name: maxTokens
              value: "4096"

    每個 config 只能擇一使用 value、expression 或 template，這是 CRD 層強制的限制。

  3. 配置參數​

    semanticLayer（必填）​

    要查詢的語意模型名稱。模型會依據這個語意模型描述的資料表與欄位結構產生 SQL，因此語意模型涵蓋的範圍就是這個 processor 能回答的範圍。

    query（必填）​

    要轉換成 SQL 的自然語言問題。實務上通常用 expression 帶入使用者的提問，詳細說明請參考：Expression 介紹 - 取值方式。

    resultField（必填）​

    儲存結果的變數名稱。結果是一個 JSON 物件，同時包含查詢結果與模型產生的那段 SQL。

    SQL 一併回傳這點在除錯時很有用：當結果不如預期，可以直接看到模型實際下了什麼語句，判斷問題出在語意模型的描述還是問題本身的表達。

    completionModel（必填）​

    用來產生 SQL 的語言模型名稱。

    maxTokens（必填）​

    模型產生內容的 token 上限。

    temperature​

    模型的隨機性參數。產生 SQL 屬於需要精確度的任務，通常設定較低的值以減少語句變異。

  4. 連接關係​

    success​

    當 SQL 成功產生並執行完成時，工作流程會從此連接點繼續執行，結果寫入 resultField 指定的變數。

    failure​

    當模型無法產生有效 SQL，或 SQL 執行失敗時，工作流程會從此連接點繼續執行，並產生 prevError 變數儲存錯誤資訊。

  5. 注意事項​

    1. 語意模型的欄位描述品質直接決定 SQL 的正確性。欄位命名含糊或缺少說明時，模型容易選錯資料表。

    2. 建議連接 failure 分支。自然語言問題落在語意模型涵蓋範圍之外時，這個 processor 會失敗，而這在開放式提問中相當常見。

    3. 需要視覺化編輯的工作流程，改用 SQL processor 搭配預先寫好的語句，或用 LLM Completion 掛載語意模型。這兩者在 Flow Agent 編輯器中都有對應節點。

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們