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

LLM Query Database

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

基本用法​

執行時會將設定的自然語言問題交給指定的語言模型，模型依據語意模型（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 是其中之一。

設定方式​

在 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 層強制的限制。

配置參數​

semanticLayer（必填）​

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

query（必填）​

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

resultField（必填）​

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

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

completionModel（必填）​

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

maxTokens（必填）​

模型產生內容的 token 上限。

temperature​

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

連接關係​

success​

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

failure​

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

注意事項​

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

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

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