用 QSyn 打造有你自己知識的 AI 助理

01QSyn 是什麼

一句話:把你的知識與系統,變成一個會對話、會查資料、會辦事的 AI 代理人。

QSyn 是一個 AI 代理人平台。你在一個工作區裡建立代理人,餵給它你的文件與知識,勾選它能用的工具,然後把它放到需要的地方——網站上的聊天泡泡、Telegram/LINE 等聊天平台,或讓它按排程自動辦事。

它和一般聊天機器人的差別在於:代理人跑的是真正的工具使用迴圈——它會自己決定要不要查知識庫、呼叫你的 API、搜尋網路,拿到結果後再回答,而不是只憑訓練資料瞎猜。

02核心概念

先認得這幾個詞,後面的說明會順很多。

• 工作區(Workspace)——你的租戶空間。代理人、知識、通道、用量都屬於某個工作區;你可以隸屬多個工作區,用左上角切換。
• 代理人(Agent)——一組具名的助理設定:系統提示(人設與規則)、使用的模型、掛上的知識與工具。
• 知識(Knowledge)——代理人可以查的資料:知識庫(上傳文件做 RAG 問答)與 Wiki(整理成文章)。
• 工具(Tool)——代理人可以「做」的動作:內建工具(搜尋、程式、圖片)與你自建的 API 工具。
• Credit(額度)——用量的計價單位。對話、生成、媒體處理都會依 token 換算成 credit,計入工作區的方案額度。

03快速上手:五分鐘做出第一個代理人

這是一段實際流程,照順序做即可。

1. 建立代理人

   側欄進入「代理人」,新增一個。給它名稱,寫下系統提示——也就是它的身分、語氣與該遵守的規則。

2. 餵知識

   建一個知識庫,上傳你的文件(產品說明、SOP、FAQ),回到代理人把這個知識庫勾起來。它回答時就會先查你的資料。

3. 勾選工具

   在代理人的「工具」分頁,依需要打開網路搜尋、生成圖片,或掛上你自己的 API 工具。勾了什麼,它就會什麼。

4. 對話測試

   直接在代理人頁面跟它聊,確認它會查知識、用對工具、語氣正確。不滿意就回頭改系統提示。

5. 上線

   把它接到通道(Telegram/LINE…),或發布嵌入、產生託管連結放到網站上。詳見下方各章。

04代理人

代理人是 QSyn 的核心。其他一切——知識、工具、通道——都是掛在代理人上的能力。

你在代理人的編輯頁一次設定好它的全部:身分、能查的知識、能用的工具、對外行為。設定會即時存檔,你可以在同一頁直接對話測試。

系統提示(它是誰、怎麼做事)

每個代理人有一段系統提示,決定它的身分、語氣與規則。這是你調整行為最主要的地方——想要它只用繁體中文、回答前一定先查知識、遇到不確定就反問、拒答範圍外的問題,都寫在這裡。改系統提示通常比加工具更能解決「答得不對」的問題。

掛上知識

把知識庫或 Wiki 勾給代理人,它回答時就會先檢索你的資料再作答。你也可以給某些知識庫寫入權限,讓代理人在對話中把新學到的內容存回去。

勾選工具

在「工具」分頁決定它能做什麼:內建工具(搜尋、程式、圖片)、資料表讀寫,或你自建的 API 工具。詳見 工具 一章。勾了什麼,它在對話與各通道就會什麼。

模型等級與思考迴圈

你可以為代理人選擇模型等級(能力與成本的取捨)。它跑的是工具使用迴圈:收到問題後,可能先查知識、呼叫一或多個工具,拿到結果再回答;必要時會連續用好幾輪工具才給出結論。你可以選擇對外要不要顯示這段思考過程——完全隱藏、只顯示階段(思考中/使用工具),或完整攤開。

可替換字元

系統提示與排程訊息裡可以用替換字元,執行時自動填入:

• {agent_name} / {workspace_name}——代理人與工作區名稱。
• {current_time}——目前時間,讓它知道「今天」是哪天。
• {sender_name} / {channel_name}——在通道對話時,對方與通道的名稱(嵌入訪客為空)。

發布與公開設定

要讓外部人用(嵌入、託管頁、公開通道),先把代理人發布。發布後可在「嵌入」面板細調對外行為與外觀。發布動作有審計紀錄。

05知識庫與 Wiki

兩種餵知識的方式,用途不同,兩者都能掛到代理人上被查詢。

知識庫(Knowledge Base)

上傳文件,QSyn 會非同步建立索引;代理人回答時用檢索增強(RAG)——先找出相關段落再據以作答,並可註明出處。適合 FAQ、產品文件、內部 SOP。

• 上傳與處理——文件上傳後進入處理佇列(排隊 → 完成/失敗),完成後才會被檢索到;可查看每份文件的處理狀態。
• 問答——你或代理人以自然語言提問,系統回傳依據你文件的答案與出處段落。
• 管理——卡片可隨時改名稱與描述;可刪除個別文件。
• API 化——知識庫可透過 REST API 新增、擷取、查詢,見 REST API。

Wiki

Wiki 從你提供的來源(上傳檔或網址)整理出結構化文章,可對外發布成知識庫網站。適合把零散資料變成一篇篇可閱讀、可分享的內容。

• 來源 → 文章——加入來源後,系統生成對應文章;生成時會先偵測語言,確保整篇語言一致(不會繁簡混雜)。
• 刪除與連動——可刪單篇文章;刪來源時可選擇一併封存「只由該來源產生」的文章,多來源共用的文章則保留。
• 發布——整理好的 Wiki 可發布給外部閱讀。

06工具

工具讓代理人不只會講,還會做。工具在代理人的「工具」分頁勾選。

內建工具

• 網路搜尋 / 網頁擷取——查即時資訊、讀取指定網頁內容。
• 程式執行——跑運算、轉換與處理資料。
• 生成圖片——依文字描述產出圖片。
• 知識工具——查詢掛上的知識庫與 Wiki。
• 資料表工具——讀寫結構化資料表,可當作代理人的記憶或清單。
• 詢問使用者(ask_user)——需要更多資訊時,以選項形式反問對方。

工具搜尋模式(工具很多時)

當你在工具庫掛了很多工具,可開啟工具搜尋:代理人先依需要找出相關工具再呼叫,而不是每回合都把全部工具塞進上下文——省成本也更穩。

自建工具(串你自己的 API)

你可以讓代理人呼叫自家系統的 API。在工具設定填:

• base URL、HTTP 方法、路徑——這支工具打哪裡。
• 標頭與認證——例如 Authorization: Bearer {{token}}。{{...}} 是伺服器端的機密替換,值永遠不會透露給模型。
• 參數——你描述每個參數,模型依對話內容自己填。

所有自建工具的外呼都經過 SSRF 防護(擋掉打內網/雲端中繼位址的嘗試),並有連線逾時保護。編輯器裡有測試按鈕:填入範例參數就能看到實際回應,方便你在掛給代理人前先確認接得通。

07通道

把代理人接到人們原本就在用的聊天平台。

通道讓代理人在 Telegram、LINE、Discord、Email 上直接對話。你選一個代理人、接上該平台的憑證,對方在那個平台傳訊,代理人就會回。訊息以非同步方式處理——回覆透過各平台自己的 API 送回,所以就算代理人查資料花點時間也不會卡住,群組裡它也能判斷某句話不是在跟它講而選擇不回。

• 每日上限與自訂回應——公開平台上任何人都找得到你的機器人,所以每個通道可設每日 credit 上限當花費防線,並能自訂「達上限時的回應」。
• 對話紀錄——後台可查看誰跟這個通道講過話、問了什麼;可刪除或清空。
• Email——以收信方式運作,收到郵件即交給代理人處理並回信。
• 通道改名——名稱可隨時編輯。

08排程任務

讓代理人按時間自動辦事。

排程任務就是「在某個時間,把一段訊息交給指定的代理人,並保存它的回覆」。設定時選代理人、時間與要送的訊息即可。

• 時間——單次(某年某月某日某時)或週期(以 cron 表示,如每天 09:00),可指定時區。
• 訊息替換字元——同樣支援 {current_time} 等,讓每次觸發都帶入當下資訊。
• 回覆保存——每次執行的回覆都會存下來,可回頭查看歷次結果。

典型用法:每天早上讓代理人彙整昨日數據、每週產出報告、定時對某通道推播提醒。每個工作區能建立的排程數量依方案而定。

09管道與資料表

結構化資料與自動化流程。

資料表(Data Tables)

存放結構化資料的表格。代理人可以透過工具讀寫資料表,適合當作它的記憶、待辦清單、或可查詢的名單。資料表也完整開放 REST API(列出、查詢、新增/更新/刪除列),方便你的系統直接讀寫。

管道(Pipelines)

把多個步驟串成自動化流程(例如:接收輸入 → 呼叫模型 → 查資料 → 產出結果)。編輯器裡有 AI 助手:你用自然語言描述需求,它就能幫你整份生成管道,再由你微調。

管道可以被程式觸發,有兩種方式:用工作區密鑰走 POST /api/v1/pipelines/:id/runs,或用該管道專屬的 API token 走同步的 POST /api/v1/pipelines/:id/invoke(像呼叫一個 LLM API 一樣,直接拿到輸出)。細節見 REST API。

10嵌入到你的網站

兩種把代理人放上網站的方式,不用寫太多程式。

託管對話頁(最快)

幫代理人產生一個 QSyn 託管的滿版對話網址(形如 /e/你的代碼),直接把連結分享出去即可,不需要嵌入任何程式碼。連結本身就是憑證,所以啟用時必須設每日 credit 上限當花費防線,並可自訂達上限時的回應。分頁標題會自動用代理人名稱。

嵌入 widget

把聊天元件放進你自己的網站,像客服泡泡一樣。你可以決定外觀與行為:

• 版面——浮動泡泡(bubble)或內嵌填滿容器(inline)。
• 思考顯示——關閉、簡要階段標籤,或完整思考過程。
• 圖片、標題、開場白、頭像、多對話切換——都能開關與自訂。
• 品牌標記——付費方案可關閉「Powered by QSyn」。

公開嵌入用公開金鑰(qpk_…);金鑰用量計費到金鑰擁有者的工作區,並可設每日上限。訪客能用的工具,就是你在代理人「工具」分頁勾選的那些。

11金鑰(API Keys)

QSyn 有兩種金鑰,用途與安全性完全不同——用錯會出事,先分清楚。

兩種金鑰都在後台的金鑰設定頁建立與管理。金鑰的完整明文只在建立當下顯示一次,關掉就看不到了,請當場存進你的密鑰管理工具。之後系統只留雜湊,無法再取回原文;弄丟就撤銷重發。

密鑰(Secret key)

給伺服器對伺服器使用,擁有工作區的完整能力,是呼叫 REST API 的憑證。放在你的後端環境變數裡,永遠不要出現在瀏覽器、前端程式或版本庫。認證時二擇一:

Authorization: Bearer qsk_xxxxxxxx
# 或
X-API-Key: qsk_xxxxxxxx

建立時 API 回傳一次明文(key 欄位),之後只看得到前綴:

{
  "id": "…",
  "name": "server integration",
  "prefix": "qsk_xxxxxxxx",
  "type": "secret",
  "key": "qsk_…完整明文,只在這次回傳…"
}

公開金鑰(Publishable key)

設計來放在網頁上供嵌入 widget 使用。它做得到的事被刻意限縮:

• 綁定單一代理人——一把金鑰只能驅動它被發給的那個代理人,不能拿去打別的。
• 環境——live(正式,計費)或 test(開發用,不計費、允許任何來源、額度低)。
• 來源網域白名單——限制哪些網站能用這把 live 金鑰。
• 每日 credit 上限——公開金鑰務必設,因為金鑰放在網頁上等於誰都拿得到;上限是花費防線。管理員可「重置今日用量」讓被擋住的金鑰在午夜前恢復。

Session token(不放金鑰的第三種方式)

適合已登入的內部系統:頁面上完全不放金鑰,改由你的後端驗證登入者後向 QSyn 換發一組短效 session token 給 widget(widget 自動續期)。誰能用、能用多久,由你的後端說了算。實作見 嵌入整合 SDK。

12REST API

用密鑰從你的系統直接呼叫 QSyn:代理人、管道、知識庫、Wiki、資料表。

所有外部端點都在 /api/v1 底下,以密鑰認證(見 金鑰),base URL 為你的部署網域。請求與回應皆 JSON;串流端點回傳 SSE 事件。每把金鑰預設每分鐘 120 次速率限制。

呼叫代理人

最常用的端點。送一句話或多輪訊息,回傳 SSE 事件串流(thinking / text / tool_use / tool_result / done)。代理人用的是它已存的設定(系統提示、知識、工具),你只需給訊息。

curl -N https://qsyn.dynara.io/api/v1/agents/AGENT_ID/stream \
  -H "Authorization: Bearer qsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"input":"幫我摘要這週的工單"}'

# 帶多輪對話:
  -d '{"messages":[{"role":"user","content":"…"}]}'

查詢知識庫

curl https://qsyn.dynara.io/api/v1/kb/KB_ID/query \
  -H "X-API-Key: qsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"question":"退貨流程是什麼?"}'

端點總覽

各端點詳細參數

路徑都在 /api/v1 底下。必填 以顏色標示;路徑參數(如 :id)一律必填。

呼叫一個已存的代理人。用它自己的系統提示、知識與工具;你只給訊息。回傳 SSE 事件串流。

回應:text/event-stream —— 事件型別 thinking / text / tool_use / tool_result / done。

非同步觸發一次管道執行。

回應 202:{ "run_id": "…", "status": "running" }

列出這個管道的執行紀錄。

回應:{ "runs": [ … ] },每筆含 status、output、trace、interrupt、tokens_used。

續跑一個停在等待節點的執行。

回應 202:{ "run_id": "…", "status": "running" }。若該執行不在等待中,回 409。

同步呼叫,完成才回傳、直接拿到輸出(像呼叫一個 LLM API)。認證用該管道專屬的 API token,不是工作區密鑰。

Body:任意 JSON,作為管道 input(空 body 視為 {})。回應:管道輸出;執行失敗回 502 並附 status。

以自然語言問答,依你上傳的文件作答。

回應:答案與依據段落(出處)。

新增一條結構化知識(主-謂-賓三元組)。

回應 200:{ subject, relation, object }

丟一段文字,系統自動抽取三元組並寫入知識庫。

回應:實際寫入的條目清單。

上傳文件到知識庫(multipart/form-data)。

回應:建立一個處理工作(ingestion job);用下面的端點輪詢狀態,完成後才會被檢索。

查詢文件處理狀態。

回應:工作狀態(queued → processing → completed / failed)。

刪除一份文件及其索引。

查詢已發布的 Wiki 內容。

回應:依 Wiki 內容作答。

新增一個文字來源,系統會據以生成文章。

回應 202:{ source, run_id }(生成非同步進行)。

上傳檔案作為來源(multipart/form-data)。

取得單一來源(含處理狀態)。

以 source_id 刪除該來源及其衍生的 chunk / proposal(已發布文章預設保留)。

回應 200:{ deleted, archived_articles }。archived_articles 為本次連帶封存的文章數(未帶 cascade 時恆為 0)。

列出工作區的資料表。

建立資料表。

回應 201:建立的資料表(含正規化後的欄位)。

取得資料表(含欄位定義)。

列出資料列。回應:{ rows: [ … ] }。

以條件查詢資料列(過濾、排序、限制、展開關聯)。

回應:{ rows, count }。

新增一列。

回應 201:{ row }。違反唯一性回 409。

更新一列。

回應 200:{ "message": "updated" }。

刪除一列。

建立一個排程任務:在指定時間把一段訊息送給某個代理人。

回應:{ task }(含 id、next_run_at 等)。超過方案的排程數量上限回 402。

列出工作區的排程任務。回應:{ tasks, count, limit }。

取得單一排程。

更新排程。Body 欄位同 POST /tasks(整筆取代)。

刪除排程(連同其執行紀錄)。

列出這個排程的歷次執行(狀態、輸出、錯誤)。

不管排程時間,立即執行一次。回應 202:{ "status": "started" }。

錯誤與限制

• 401——缺少或無效的密鑰;用公開金鑰(qpk_)打 /api/v1 會被拒(此處只收 qsk_)。
• 402——工作區額度用盡。
• 429——超過速率限制(預設每分鐘 120 次)。
• 404 / 409——資源不存在,或狀態不允許(如管道已暫停)。

13嵌入整合 SDK

實際把 widget 放上頁面的三種寫法。把 qpk_live_… 換成你的公開金鑰、AGENT_ID 換成代理人 ID。

一段式:自動掛載

最簡單。貼上 script,設好 data 屬性即可,適合公開網站的浮動泡泡。

<script
  src="https://qsyn.dynara.io/embed/v1.js"
  data-key="qpk_live_xxxxxxxx"
  data-agent="AGENT_ID"
  data-layout="bubble"
  async></script>

兩段式:用 mount() 控制選項

需要指定容器或自訂更多選項時用這種。第一段載入 SDK,第二段呼叫 QSyn.mount(target, options)。

<script src="https://qsyn.dynara.io/embed/v1.js" async></script>
<script>
  QSyn.mount("#qsyn-chat", {
    key: "qpk_live_xxxxxxxx",
    agent: "AGENT_ID",
    layout: "inline",
    title: "客服小幫手",
    greeting: "嗨,有什麼可以幫你?",
  });
</script>

session 認證:頁面不放金鑰

適合已登入的內部系統。頁面上不放任何金鑰;改由你自己的後端驗證登入者之後簽發一組短效 session token 回傳給 widget(widget 會自動續期)。你只要提供一個回傳 token 的端點,填在 sessionUrl。

<script src="https://qsyn.dynara.io/embed/v1.js" async></script>
<script>
  QSyn.mount(document.body, {
    // 由你的後端驗證登入者後簽發短效 session token
    sessionUrl: "/api/assistant/embed-session",
    layout: "bubble",
  });
</script>

14方案與額度

用量以 credit 計。方案決定額度與各項功能的數量上限。

對話、生成、媒體處理(圖片轉文字、語音)都會依 token 換算成 credit,計入工作區當期額度。免費方案有基本額度並固定顯示 QSyn 品牌標記;付費方案有更高額度、可關閉品牌標記,並提高排程數、通道數等上限。

15帳號與工作區

一個帳號,可以隸屬多個工作區。

• 切換工作區——左上角切換目前所在的工作區;代理人、知識、用量都是各工作區獨立的。
• 工作區名稱——可獨立自訂(與你的顯示名稱互不相干),到工作區設定修改,左上角會即時更新。
• 顯示名稱與頭像——在帳號設定修改,是跨工作區的個人資料。
• 成員與角色——工作區可有多位成員;部分設定(如發布、清空紀錄)僅工作區管理員可操作。

16名詞對照

中英名詞快速對照,避免混淆。

工作區 Workspace

你的租戶空間,一切資源歸屬於此。

代理人 Agent

具名的 AI 助理設定。

知識庫 Knowledge Base

上傳文件做 RAG 問答。

通道 Channel

接到 Telegram/LINE/Discord/Email。

管道 Pipeline

多步驟自動化流程(注意:與「通道」不同)。

密鑰 Secret key

伺服器端呼叫 API 的金鑰,前綴 qsk_,勿放前端。

公開金鑰 Publishable key

放在網頁上的嵌入金鑰,前綴 qpk_。

託管頁 Hosted page

QSyn 託管的分享對話網址 /e/…。

額度 Credit

用量計價單位,依 token 換算。