在 C# 中使用 Aspose.LLM 持久化和恢復聊天會話

持久化聊天會話可讓您的 .NET 應用程式在重新啟動後仍能運行，提供對話的備份，並允許在不同機器之間搬移會話。在本指南中，我們將使用 Aspose.LLM 逐步說明 在 C# 中持久化並恢復聊天會話，涵蓋何時使用此模式、如何儲存與載入會話、會存儲哪些資料、可移植性考量以及安全性最佳實踐。

為什麼要持久化並恢復聊天會話？

開發人員常常構建交互式助手、支援機器人或長時間運行的資料分析工作流程。在許多情況下，聊天上下文必須在單一程序的生命週期之外仍然存在：

桌面支援工具，使用者期望在關閉應用程式後先前的查詢仍然可用。
伺服器端自動化，涵蓋多個步驟，且可能因維護而重新啟動。
審計或合規需求，需要對整個對話進行快照。
將故障排除會話從開發人員的筆記型電腦移至生產伺服器。

透過將會話持久化到 JSON 檔案，您可以捕獲完整的訊息歷史記錄以及實現精確延續所需的內部 KV 快取，從而使上述使用情境的實作變得簡單直接。

開始使用 Aspose.LLM

首先，將 Aspose.LLM 套件新增至您的專案：

Install-Package Aspose.LLM

您可以在 Aspose.LLM .NET 產品頁面上找到更多產品詳細資訊。SDK 需要有效的授權，請確保您已準備好臨時或永久授權檔案。

先決條件

安裝 Aspose.LLM NuGet 套件。
使用 Aspose.LLM.License 套用 Aspose.LLM 授權。
建立 AsposeLLMApi 實例（例如，使用 Qwen25Preset）。

何時使用此模式

此模式在您需要對話在當前流程之外持續存在，或希望獲得可靠的備份或遷移快照時表現出色。典型情況包括：

桌面或伺服器應用程式，使用者期望聊天在重新啟動之間持續。
需要長時間執行的工作流程，讓對話持續超過程序的生命週期。
透過對活躍對話進行快照，以備份和稽核之用。
在具有相同 SDK 版本和預設設定的機器之間遷移會話狀態。

前置條件

在您能夠保存或還原會話之前，請確保以下條件已就緒：

Aspose.LLM NuGet package – 已透過先前顯示的指令安裝。
License – 建立 Aspose.LLM.License 物件，並使用您的 .lic 檔案呼叫 SetLicense。
API instance – 使用所需的預設（例如 new Qwen25Preset()）實例化 AsposeLLMApi。

這些步驟在本文稍後的完整範例中示範。

保存會話

SDK 提供三種方便的方法來持久化聊天會話。請按照以下步驟操作，然後查看代碼示例。

如果需要將檔案儲存在已知位置，請使用明確的檔案路徑呼叫 SaveChatSession。
省略路徑，讓 SDK 在可執行檔旁邊寫入 <sessionId>.json。
使用 Path.Combine 建立臨時路徑，確保目錄存在，然後在隔離或沙盒情境下儲存。

程式碼範例 – 儲存工作階段

以下示例演示了所有三種方法：

api.SaveChatSession(sessionId, "session-42.json");

api.SaveChatSession(sessionId); // writes <sessionId>.json next to the executable

string path = Path.Combine(Path.GetTempPath(), "chats", $"{sessionId}.json");
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
api.SaveChatSession(sessionId, path);

*api.SaveChatSession(sessionId, "session-42.json") 將 JSON 檔案寫入提供的位置。
*如果在未提供路徑的情況下呼叫 SaveChatSession，SDK 會在當前工作目錄中建立一個以會話 ID 命名的檔案。
*當您需要確定的或臨時的位置時，將 Path.GetTempPath 與您自己的資料夾結構結合，並在儲存之前建立目錄。

注意: 這些程式碼片段取自官方 Aspose 文件，尚未在沙箱中執行。請在您的環境中驗證它們，然後再於生產環境中使用。

復原會話

載入先前已儲存的會話同樣簡單。API 會讀取 JSON 檔案，重新建立內部狀態，並返回會話識別碼，讓您可以在不手動傳遞 ID 的情況下繼續傳訊。

呼叫 LoadChatSession 並提供 JSON 檔案的路徑。
儲存回傳的 sessionId。
使用 SendMessageToSessionAsync 搭配已還原的 ID 繼續對話。

程式碼範例 – 還原會話

string sessionId = await api.LoadChatSession("session-42.json");
string reply = await api.SendMessageToSessionAsync(sessionId, "What did we discuss?");

LoadChatSession 讀取檔案並返回還原的會話 ID。 還原的會話會自動設為活動會話，允許立即呼叫 SendMessageToSessionAsync。

注意： 這些程式碼片段取自官方 Aspose 文件，未在沙盒中執行。請在您的環境中驗證後再於生產環境使用。

完整範例 — 儲存、重新啟動、恢復

以下是一個完整的端到端示範。第一個區塊啟動聊天，發送幾條訊息，並儲存會話。第二個區塊模擬一個新流程，載入已儲存的檔案並繼續對話。

程式碼範例 – 端到端工作流程

using Aspose.LLM;
using Aspose.LLM.Abstractions.Parameters.Presets;

// ---------- First run: save ----------
{
    var license = new Aspose.LLM.License();
    license.SetLicense("Aspose.LLM.lic");

using var api = AsposeLLMApi.Create(new Qwen25Preset());

string sessionId = await api.StartNewChatAsync(sessionId: "support-ticket-1234");

await api.SendMessageToSessionAsync(sessionId,
        "Customer reports that the migration from v25 to v26 broke their startup script.");
    await api.SendMessageToSessionAsync(sessionId,
        "Their environment: Windows Server 2022, .NET 8, CUDA 12.6.");
    await api.SendMessageToSessionAsync(sessionId,
        "What questions should I ask them next?");

api.SaveChatSession(sessionId, "support-ticket-1234.json");
    Console.WriteLine("Session saved.");
}

// ---------- Second run: resume ----------
{
    var license = new Aspose.LLM.License();
    license.SetLicense("Aspose.LLM.lic");

using var api = AsposeLLMApi.Create(new Qwen25Preset());

string sessionId = await api.LoadChatSession("support-ticket-1234.json");
    Console.WriteLine($"Resumed session: {sessionId}");

string reply = await api.SendMessageToSessionAsync(sessionId,
        "They replied that they use a custom build step that copies native DLLs. How should I proceed?");
    Console.WriteLine(reply);
}

第一段程式碼建立授權，使用 Qwen25Preset 實例化 API，啟動名為 support-ticket-1234 的新聊天，發送三條訊息以建立上下文，最後將會話寫入 support-ticket-1234.json。第二段程式碼重新建立授權和 API，載入 JSON 檔案，並繼續對話，示範模型保留了先前的訊息。

注意： 這些程式碼片段取自官方 Aspose 文件，未在沙箱中執行。請在您的環境中驗證後再於生產環境使用。

保存了什麼？

SaveChatSession 產生一個包含三個基本部分的 JSON 文檔：

Session Identifier – 您在開始聊天時提供的唯一 ID。
Message History – 所有使用者和助理訊息的有序列表，包含角色、內容以及任何媒體的中繼資料。
KV Cache Metadata – 每條訊息的鍵值快取的內部位置和大小，使模型能夠精確地從中斷處繼續。

因為包含了快取資料，恢復的會話可以在不重新計算先前注意力的情況下繼續生成，使得恢復操作快速且具決定性。

可移植性限制

雖然 JSON 檔案包含了完美延續所需的全部內容，但它僅在特定條件下才具可移植性：

相同的 SDK 主版本 – 檔案格式可能在主要版本之間變更，因此雙方必須使用相同的 Aspose.LLM 主版本。
相同的模型檔案 – 基礎的 Hugging Face 模型（包括量化）必須完全相同；否則 KV 快取將不相容。
匹配 BinaryManagerParameters.ReleaseTag – 用於載入模型的 llama.cpp 執行階段版本必須相同，否則低階張量佈局會不同。

如果違反了任何這些約束，您可能會看到類似 InvalidOperationException 的錯誤或輸出亂碼。

已知的載入時細節

當您呼叫 LoadChatSession 時，SDK 會重建對話，但會套用預設的 ContextParameters、ChatParameters 和 SamplerParameters。您在原始會話中使用的任何自訂設定（例如溫度、最大標記數、系統提示）不會自動還原。若要保持完全相同的生成行為，請在載入後重新套用您的自訂參數，或在新會話中以所需設定重播對話。

常見錯誤

以下是一個快速檢查清單，列出在載入會話時可能遇到的常見問題：

FileNotFoundException – 驗證檔案路徑；相對路徑會相對於當前工作目錄解析。
InvalidOperationException on load – 表示 SDK 版本不相容或 JSON 檔案已損毀。
Garbled output after load – 通常是模型檔案或 ReleaseTag 不匹配所致。確保載入機器上存在完全相同的模型二進位檔。

優雅地處理這些例外並記錄詳細的診斷資訊，將使您的應用程式更加健壯。

安全性

持久化的 JSON 檔案包含每個使用者和助理訊息的 純文字 副本。將其存放在未受保護的位置可能會暴露敏感資料。請考慮以下緩解措施：

在寫入磁碟之前加密檔案（例如，Windows DPAPI、Azure Key Vault，或像 libsodium 這樣的跨平台函式庫）。
限制檔案系統權限，僅允許執行應用程式的服務帳戶讀寫檔案。
若檔案必須在網路上傳輸，請使用 TLS 加密通道，並考慮對檔案簽名以偵測篡改。

接下來

現在您可以持久化並恢復聊天，您可能想探索相關功能：

多回合聊天使用情境 – 在多次互動中維持更長的對話。
自訂預設配置 – 在持久化之前，將模型預設調整為您的領域。
完整的會話持久化參考 – 檢視 API 參考，以深入了解 SaveChatSession 及相關的中繼資料語意。

選擇正確的方法

本文介紹了三種保存會話的方法以及一個簡單的載入方式。請選擇符合您部署情境的方法：

Explicit path – 最佳情況是檔案必須位於已知位置，例如使用者特定的資料夾或共享網路磁碟。
Default filename – 方便用於快速原型或當會話與可執行檔一起存在時。
Temporary path with directory creation – 適用於沙箱環境、CI 管道，或當您希望作業系統負責清理時。

所有方法都使用相同的底層 API；它們僅在文件系統的管理方式上有所不同。

取得免費授權

如果您尚未擁有永久授權，您可以從 Aspose 臨時授權頁面獲得臨時評估授權。

免費的其他資源

結論

使用 Aspose.LLM 持久化聊天會話可為您提供耐久性、可審計性以及在不同進程或機器之間移動對話的靈活性。您已了解何時應用此模式、如何以三種不同方式保存會話、如何還原會話、JSON 文件包含的內容，以及需要注意的相容性和安全性考量。掌握完整範例後，您現在可以將會話持久化整合到任何 .NET 聊天解決方案中。

常見問題

何時持久化聊天會話有用？
持久化對於需要在啟動之間保留對話狀態的桌面或伺服器應用程式、長時間執行的工作流程、審計或備份需求，以及在具有相同 SDK 版本的機器之間遷移會話時很有幫助。
如何在保存會話時指定自訂檔案路徑？
呼叫 api.SaveChatSession(sessionId, "myfolder\myfile.json"); 或使用 Path.Combine 建構路徑，並確保在保存之前目錄已存在。
LoadChatSession 會回傳什麼？
它回傳已還原的會話識別碼，讓您可以在不再次提供 ID 的情況下繼續發送訊息。
我可以將已保存的會話檔案移至其他機器嗎？
可以，只要目標機器使用相同的主要 SDK 版本、相同的模型檔案，且 llama.cpp ReleaseTag 相符。
已保存的 JSON 檔案安全嗎？
該檔案以純文字儲存對話資料，因此應在存放於不受信任的位置之前先加密。
為什麼載入後我的自訂抽樣器或上下文設定未被還原？
LoadChatSession 會套用預設參數；載入後請重新套用任何自訂設定，或在新會話中重播歷史記錄。

為什麼要持久化並恢復聊天會話？#

開始使用 Aspose.LLM#

何時使用此模式#

前置條件#

保存會話#

復原會話#

完整範例 — 儲存、重新啟動、恢復#

保存了什麼？#

可移植性限制#

已知的載入時細節#

常見錯誤#

安全性#

接下來#

選擇正確的方法#

取得免費授權#

免費的其他資源#

結論#

常見問題#

閱讀更多#