|
1 | 1 | # llmapi |
2 | 2 |
|
3 | | -> Modern C++ LLM API client with openai-compatible support |
| 3 | +> 使用 C++23 模組建構的現代 LLM 客戶端 |
4 | 4 |
|
5 | 5 | [](https://en.cppreference.com/w/cpp/23) |
6 | 6 | [](https://en.cppreference.com/w/cpp/language/modules) |
7 | 7 | [](LICENSE) |
8 | | -[](https://platform.openai.com/docs/api-reference) |
| 8 | +[](https://platform.openai.com/docs/api-reference) |
9 | 9 |
|
10 | 10 | | [English](README.md) - [简体中文](README.zh.md) - 繁體中文 | |
11 | 11 | |:---:| |
12 | | -| [完整文件](docs/) - [C++ API](docs/cpp-api.md) - [C API](docs/c-api.md) - [範例](docs/examples.md) | |
| 12 | +| [文件導覽](docs/README.md) - [繁體中文文件](docs/zh-hant/README.md) - [English Docs](docs/en/README.md) - [简体中文文档](docs/zh/README.md) | |
13 | 13 |
|
14 | | -簡潔、型別安全的 LLM API 客戶端，使用 C++23 模組。流式介面設計，零成本抽象。支援 OpenAI、Poe、DeepSeek 及相容端點。 |
| 14 | +`llmapi` 提供型別化的 `Client<Provider>` API，涵蓋聊天、串流輸出、embeddings、工具呼叫與對話持久化。預設別名 `Config` 對應 OpenAI 風格設定，常見情況下不需要顯式寫出 `openai::OpenAI(...)`。 |
15 | 15 |
|
16 | | -## ✨ 特性 |
| 16 | +## 特性 |
17 | 17 |
|
18 | | -- **C++23 模組** - `import mcpplibs.llmapi` |
19 | | -- **自動儲存歷史** - 對話歷史自動管理 |
20 | | -- **型別安全串流** - 概念約束的回呼函式 |
21 | | -- **流式介面** - 可鏈式呼叫的方法 |
22 | | -- **提供商無關** - OpenAI、Poe 及相容端點 |
| 18 | +- C++23 模組：`import mcpplibs.llmapi` |
| 19 | +- 強型別訊息、工具與回應結構 |
| 20 | +- 同步、非同步、串流聊天介面 |
| 21 | +- OpenAI Provider 支援 embeddings |
| 22 | +- 支援儲存 / 載入對話歷史 |
| 23 | +- 可透過 `baseUrl` 存取 OpenAI 相容端點 |
23 | 24 |
|
24 | | -## 快速開始 |
| 25 | +## 生產可用性 |
| 26 | + |
| 27 | +`llmapi` 目前適合內部工具、原型專案與早期生產試用，但還不應直接視為完整工業級基礎設施。 |
| 28 | + |
| 29 | +要達到那個標準，至少還需要補齊： |
25 | 30 |
|
| 31 | +- 統一的 provider / 傳輸層錯誤模型 |
| 32 | +- 重試、退避、逾時、冪等策略 |
| 33 | +- 長請求與串流請求的取消能力 |
| 34 | +- 日誌、指標、trace hook、請求關聯資訊 |
| 35 | +- 自研 HTTP/TLS 傳輸層的進一步加固 |
| 36 | +- 故障注入、並發、Mock、大規模測試 |
| 37 | +- 更強的 API 相容性與版本穩定性承諾 |
| 38 | +- 更完整的生產設定面 |
| 39 | +- 明確的執行緒安全與並發語義 |
| 40 | +- 面向維運的重試、金鑰、代理、故障處理文件 |
| 41 | + |
| 42 | +## 快速開始 |
26 | 43 |
|
27 | 44 | ```cpp |
28 | | -import std; |
29 | 45 | import mcpplibs.llmapi; |
| 46 | +import std; |
30 | 47 |
|
31 | 48 | int main() { |
32 | | - using namespace mcpplibs; |
33 | | - |
34 | | - llmapi::Client client(std::getenv("OPENAI_API_KEY"), llmapi::URL::Poe); |
35 | | - |
36 | | - client.model("gpt-5") |
37 | | - .system("You are a helpful assistant.") |
38 | | - .user("In one sentence, introduce modern C++. 並給出中文翻譯") |
39 | | - .request([](std::string_view chunk) { |
40 | | - std::print("{}", chunk); |
41 | | - std::cout.flush(); |
42 | | - }); |
| 49 | + using namespace mcpplibs::llmapi; |
| 50 | + |
| 51 | + auto apiKey = std::getenv("OPENAI_API_KEY"); |
| 52 | + if (!apiKey) { |
| 53 | + std::cerr << "OPENAI_API_KEY not set\n"; |
| 54 | + return 1; |
| 55 | + } |
| 56 | + |
| 57 | + auto client = Client(Config{ |
| 58 | + .apiKey = apiKey, |
| 59 | + .model = "gpt-4o-mini", |
| 60 | + }); |
43 | 61 |
|
| 62 | + client.system("You are a concise assistant."); |
| 63 | + auto resp = client.chat("用兩句話解釋 C++23 模組的價值。"); |
| 64 | + |
| 65 | + std::cout << resp.text() << '\n'; |
44 | 66 | return 0; |
45 | 67 | } |
46 | 68 | ``` |
47 | 69 |
|
48 | | -### 模型 / 提供商 |
| 70 | +## Provider |
| 71 | + |
| 72 | +- `Config`：`openai::Config` 的匯出別名，預設走 OpenAI 風格 |
| 73 | +- `openai::OpenAI`：OpenAI 聊天、串流、工具呼叫、embeddings |
| 74 | +- `AnthropicConfig` / `anthropic::Anthropic`：Anthropic 聊天與串流 |
| 75 | + |
| 76 | +相容端點範例： |
49 | 77 |
|
50 | 78 | ```cpp |
51 | | -llmapi::Client client(apiKey, llmapi::URL::OpenAI); // OpenAI |
52 | | -llmapi::Client client(apiKey, llmapi::URL::Poe); // Poe |
53 | | -llmapi::Client client(apiKey, llmapi::URL::DeepSeek); // Deepseek |
54 | | -llmapi::Client client(apiKey, "https://custom.com"); // 自訂 |
| 79 | +auto client = Client(Config{ |
| 80 | + .apiKey = std::getenv("DEEPSEEK_API_KEY"), |
| 81 | + .baseUrl = std::string(URL::DeepSeek), |
| 82 | + .model = "deepseek-chat", |
| 83 | +}); |
55 | 84 | ``` |
56 | 85 |
|
57 | | -## 🛠️ 建置 |
| 86 | +## 建置與執行 |
58 | 87 |
|
59 | 88 | ```bash |
60 | | -xmake # 建置 |
61 | | -xmake run basic # 執行範例（需先設定 OPENAI_API_KEY） |
| 89 | +xmake |
| 90 | +xmake run hello_mcpp |
| 91 | +xmake run basic |
| 92 | +xmake run chat |
62 | 93 | ``` |
63 | 94 |
|
64 | | -## 📦 在建置工具中使用 |
65 | | - |
66 | | -### xmake |
| 95 | +## 套件管理使用 |
67 | 96 |
|
68 | 97 | ```lua |
69 | | --- 0 - 新增 mcpplibs 索引倉庫 |
70 | | -add_repositories("mcpplibs-index https://github.com/mcpplibs/llmapi.git") |
71 | | - |
72 | | --- 1 - 新增需要的函式庫和版本 |
73 | | -add_requires("llmapi 0.0.2") |
| 98 | +add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git") |
| 99 | +add_requires("llmapi 0.1.0") |
| 100 | + |
| 101 | +target("demo") |
| 102 | + set_kind("binary") |
| 103 | + set_languages("c++23") |
| 104 | + set_policy("build.c++.modules", true) |
| 105 | + add_files("src/*.cpp") |
| 106 | + add_packages("llmapi") |
74 | 107 | ``` |
75 | 108 |
|
76 | | -> More: [mcpplibs-index](https://github.com/mcpplibs/mcpplibs-index) |
77 | | -
|
78 | | -### cmake |
79 | | - |
80 | | -``` |
81 | | -todo... |
82 | | -``` |
| 109 | +更多內容見 [docs/zh-hant/getting-started.md](docs/zh-hant/getting-started.md)、[docs/zh-hant/providers.md](docs/zh-hant/providers.md) 與 [docs/zh-hant/README.md](docs/zh-hant/README.md)。 |
83 | 110 |
|
84 | | -## 📄 授權條款 |
| 111 | +## 授權 |
85 | 112 |
|
86 | | -Apache-2.0 - 詳見 [LICENSE](LICENSE) |
| 113 | +Apache-2.0，詳見 [LICENSE](LICENSE) |
0 commit comments