unlimited-ai

# unlimited-ai [English](README.md) | **日本語** [Voids API](https://voids.top/) の AI チャット補完機能の高速・軽量な Node.js ラッパーです。 > [!Note] > Voids API はこのパッケージとは無関係です。API 自体の問題については、こちらの GitHub Issue に報告しないでください。 ```sh npm install unlimited-ai ``` ## unlimited-ai is back! TypeScript で書き直されました。`axios` は `ky` に置き換えられています。会話 ID による履歴管理に対応しました — 以前はすべての呼び出しがステートレスでした。 <details> <summary>その他の変更点...</summary> `allModels()` は `models()` に改名されました。キュレーション済みモデルリストは削除されました。`searchModels()` の `all` パラメータは廃止されました。 </details> > [!Caution] > > v6.x 以下はサポートされなくなりました。 > 一部の関数はもう動かない、または仕様が変更されています。v7 かそれ以降に更新してください。 --- ## クイックスタート ```ts // ESM import { AI } from 'unlimited-ai'; // CJS const { AI } = require('unlimited-ai'); const ai = new AI({ model: 'gpt-4o', system: 'あなたは親切なアシスタントです。' }); console.log(await ai.ask('こんにちは！')); ``` 関数型 API も使えます： ```ts // ESM import { generate, ask, models } from 'unlimited-ai'; // CJS const { generate, ask, models } = require('unlimited-ai'); const list = await models(); console.log(list); // ['gpt-4o', 'gemini-1.5-flash', ...] const reply = await generate('gpt-4o', [{ role: 'user', content: 'こんにちは！' }]); console.log(reply); ``` --- ## `new AI(init?)` ```ts new AI(init?: { model?: string; system?: string; messages?: Message[]; }) ``` AI インスタンスを作成します。 **`init.model`** `string` *(省略可)* 使用するモデル ID（例: `'gpt-4o'`）。 **`init.system`** `string` *(省略可)* システムプロンプト。すべてのリクエストに `system` メッセージとして先頭に付加されます。 **`init.messages`** `Message[]` *(省略可)* 静的コンテキストの初期値。すべてのリクエストに先頭から付加されます。 --- ### 使用例 **`useConversation` による多ターン会話** ```ts // ESM import { AI } from 'unlimited-ai'; // CJS const { AI } = require('unlimited-ai'); const ai = new AI({ model: 'gpt-4o', system: 'あなたは親切なアシスタントです。' }); ai.useConversation('session-1'); console.log(await ai.ask('TypeScript とは何ですか？')); console.log(await ai.ask('型システムについて教えてください。')); // 会話履歴ごと送信 ``` **ユーザーごとに独立した履歴（ID をその場で指定）** ```ts // ESM import { AI } from 'unlimited-ai'; // CJS const { AI } = require('unlimited-ai'); const ai = new AI({ model: 'gpt-4o', system: 'あなたは親切なアシスタントです。' }); await ai.ask('こんにちは！', 'user-alice'); await ai.ask('やあ！', 'user-bob'); await ai.ask('覚えてる？', 'user-alice'); // alice の履歴が復元される ``` **ステートレス** ```ts const reply = await ai.ask('2 + 2 は？'); // 静的コンテキスト＋このプロンプトだけを送信。何も保存されない。 ``` **ストリーミング** ```ts // ESM import { AI } from 'unlimited-ai'; // CJS const { AI } = require('unlimited-ai'); const ai = new AI({ model: 'gpt-4o' }); ai.useConversation('session-1'); for await (const chunk of ai.stream('ジョークを教えてください。')) { process.stdout.write(chunk); } // 完了後、全文が session-1 の履歴に自動追加される。 ``` **再起動後も会話履歴を維持する** ```ts // ESM import { AI } from 'unlimited-ai'; import { readFileSync, writeFileSync } from 'node:fs'; // CJS const { AI } = require('unlimited-ai'); const { readFileSync, writeFileSync } = require('node:fs'); const ai = new AI({ model: 'gpt-4o' }); // 起動時に保存済みの会話を復元 try { const saved = JSON.parse(readFileSync('conversations.json', 'utf-8')); ai.importConversations(saved); } catch { /* 保存ファイルがまだない */ } ai.useConversation('session-1'); console.log(await ai.ask('こんにちは！')); // 終了前に全会話を保存 writeFileSync('conversations.json', JSON.stringify(ai.exportConversations())); ``` **従来の書き方（手動で履歴を管理）** ```ts // ESM import { AI } from 'unlimited-ai'; // CJS const { AI } = require('unlimited-ai'); const ai = new AI(); const reply = await ai .setModel('gpt-4o') .addMessage({ role: 'system', content: 'あなたは親切なアシスタントです。' }) .addMessage({ role: 'user', content: 'こんにちは！' }) .generate(); console.log(reply); ``` --- ### 静的コンテキスト静的コンテキストのメッセージはすべてのリクエストに先頭から付加されます。システムプロンプトや few-shot 例の設定に使います。すべてのメソッドは `this` を返し、チェーン可能です。 --- #### `setModel(model, search?)` ```ts setModel(model: string, search?: boolean): this ``` 以降のリクエストで使用するモデルを設定します。 **`model`** `string` モデル ID（例: `'gpt-4o'`）。 **`search`** `boolean` *(省略可、デフォルト: `false`)* `true` の場合、`searchModels` によるファジー検索を行い、最も近いモデル ID を使用します。 --- #### `setSystem(content)` ```ts setSystem(content: string): this ``` システムプロンプトを設定または置き換えます。静的コンテキストに `system` メッセージが既に存在する場合はその場で置き換え、なければ先頭に追加します。 **`content`** `string` システムプロンプトのテキスト。 --- #### `setMessages(messages)` ```ts setMessages(messages: Message[]): this ``` 静的コンテキスト全体を置き換えます。 **`messages`** `Message[]` 新しい静的コンテキスト。既存の値をすべて上書きします。 --- #### `addMessage(message)` ```ts addMessage(message: Message): this ``` 静的コンテキストの末尾にメッセージを 1 件追加します。 **`message`** `Message` 追加するメッセージ（`{ role, content }`）。 --- #### `removeMessage(index)` ```ts removeMessage(index: number): this ``` 静的コンテキストから指定インデックスのメッセージを削除します。インデックスが範囲外の場合は `RangeError` をスローします。 **`index`** `number` 削除するメッセージのゼロ始まりインデックス。 --- #### `clearMessages()` ```ts clearMessages(): this ``` 静的コンテキストのメッセージをすべて削除します。 --- #### `getFormat()` ```ts getFormat(): { model: string; messages: Message[] } ``` 現在のモデルと静的コンテキストのスナップショットを返します。返される `messages` 配列はシャローコピーであり、変更してもインスタンスには影響しません。 --- #### `generate(raw?)` ```ts generate(raw?: false): Promise<string> generate(raw: true): Promise<CompletionResponse> ``` 現在の静的コンテキスト（`this.messages`）をそのまま送信し、返答を返します。 **`raw`** `boolean` *(省略可、デフォルト: `false`)* `true` の場合、返答文字列の代わりに `CompletionResponse` オブジェクト全体を返します。 --- ### 会話管理会話ごとの履歴は自動管理され、静的コンテキストとは独立して保持されます。特記のないメソッドはすべて `this` を返し、チェーン可能です。 --- #### `useConversation(id)` ```ts useConversation(id: string | null): this ``` 以降の `ask` / `stream` 呼び出しで使用するアクティブな会話を設定します。`null` を渡すとステートレスモードに戻ります。 **`id`** `string | null` 有効化する会話 ID。空でない任意の文字列が使えます（UUID、Snowflake、ユーザー名など）。新しい ID を指定した場合、空の履歴が自動的に作成されます。 --- #### `ask(prompt, id?)` ```ts ask(prompt: string, id?: string): Promise<string> ``` メッセージを送信し、返答を返します。 - `id` が指定されているか、`useConversation` でアクティブな会話が設定されている場合、ユーザーメッセージと返答がその会話の履歴に追加されます。 - ID が未指定の場合はステートレス — 静的コンテキストとこのプロンプトのみを送信し、何も保存されません。 **`prompt`** `string` 送信するユーザーメッセージ。 **`id`** `string` *(省略可)* 会話 ID。このメソッド呼び出しの間だけ、`useConversation` で設定したアクティブな会話を上書きします。 **戻り値** `Promise<string>` アシスタントの返答。 --- #### `stream(prompt, id?)` ```ts stream(prompt: string, id?: string): AsyncGenerator<string> ``` `ask` と同じですが、返答をチャンク単位でストリーミングします。ジェネレーターが完了した後、組み立てた全文が会話履歴に保存されます（ID が有効な場合）。 **`prompt`** `string` 送信するユーザーメッセージ。 **`id`** `string` *(省略可)* 会話 ID。このメソッド呼び出しの間だけアクティブな会話を上書きします。 **Yields** `string` 返答のテキストチャンク。 --- #### `listConversations()` ```ts listConversations(): string[] ``` 既存のすべての会話 ID の配列を返します。 --- #### `getConversationMessages(id)` ```ts getConversationMessages(id: string): Message[] ``` 指定した会話のメッセージ履歴のコピーを返します。返された配列を変更しても、保存済みの履歴には影響しません。 **`id`** `string` 会話 ID。 --- #### `clearConversation(id)` ```ts clearConversation(id: string): this ``` 指定した会話のメッセージ履歴を空にします。会話そのものは削除されません。 **`id`** `string` 会話 ID。 --- #### `deleteConversation(id)` ```ts deleteConversation(id: string): this ``` 指定した会話とその履歴を完全に削除します。 **`id`** `string` 会話 ID。 --- #### `exportConversations(id?)` ```ts exportConversations(id: string): Message[] exportConversations(): ConversationStore ``` 会話履歴を JSON シリアライズ可能なプレーン値としてエクスポートします。 - `id` を指定した場合、その会話の `Message[]` のコピーを返します。 - 引数なしの場合、すべての会話を含む `ConversationStore`（会話 ID をキーとするプレーンオブジェクト）を返します。 **`id`** `string` *(省略可)* 会話 ID。省略するとすべての会話をエクスポートします。 --- #### `importConversations(data, replace?)` ```ts importConversations(data: ConversationStore, replace?: boolean): this ``` プレーンオブジェクト（JSON パース済みなど）から会話を読み込みます。再起動後の履歴復元に使います。 **`data`** `ConversationStore` 会話 ID から `Message[]` 配列へのマッピングオブジェクト。 **`replace`** `boolean` *(省略可、デフォルト: `false`)* `false`（デフォルト）の場合、既存の会話にインポートした内容をマージします。`true` の場合、インポート前に既存の会話をすべてクリアします。 --- ## 関数型 API ### `generate(model, messages, raw?)` ```ts generate(model: string, messages: Message[], raw?: false): Promise<string> generate(model: string, messages: Message[], raw: true): Promise<CompletionResponse> ``` ```ts // ESM import { generate } from 'unlimited-ai'; // CJS const { generate } = require('unlimited-ai'); const reply = await generate('gpt-4o', [{ role: 'user', content: 'こんにちは！' }]); // レスポンスオブジェクト全体を取得 const raw = await generate('gpt-4o', messages, true); console.log(raw.choices[0]?.message.content); ``` チャット補完リクエストを送信し、結果を返します。 **`model`** `string` モデル ID（例: `'gpt-4o'`）。 **`messages`** `Message[]` 送信する会話メッセージ。 **`raw`** `boolean` *(省略可、デフォルト: `false`)* `true` の場合、返答文字列の代わりに `CompletionResponse` オブジェクト全体を返します。 --- ### `ask(model, prompt, system?)` ```ts ask(model: string, prompt: string, system?: string): Promise<string> ``` ```ts // ESM import { ask } from 'unlimited-ai'; // CJS const { ask } = require('unlimited-ai'); const reply = await ask('gpt-4o', 'こんにちは！', 'あなたは親切なアシスタントです。'); console.log(reply); ``` ユーザーメッセージを 1 件送信して返答を返すシンプルなヘルパーです。 **`model`** `string` モデル ID。 **`prompt`** `string` 送信するユーザーメッセージ。 **`system`** `string` *(省略可)* システムプロンプト。指定した場合、`system` メッセージとして先頭に付加されます。 --- ### `stream(model, messages)` ```ts stream(model: string, messages: Message[]): AsyncGenerator<string> ``` ```ts // ESM import { stream } from 'unlimited-ai'; // CJS const { stream } = require('unlimited-ai'); for await (const chunk of stream('gpt-4o', [{ role: 'user', content: 'こんにちは！' }])) { process.stdout.write(chunk); } ``` ストリーミングを有効にしてチャット補完リクエストを送信し、返答チャンクを順次 yield します。 **`model`** `string` モデル ID。 **`messages`** `Message[]` 送信する会話メッセージ。 **Yields** `string` 返答のテキストチャンク。 --- ### `models()` ```ts models(): Promise<string[]> ``` ```ts // ESM import { models } from 'unlimited-ai'; // CJS const { models } = require('unlimited-ai'); const list = await models(); // ['gpt-4o', 'gpt-4-turbo', 'gemini-1.5-flash', ...] ``` API から利用可能なモデル ID の一覧を取得して返します。 --- ### `searchModels(word)` ```ts searchModels(word: string): Promise<string[]> ``` ```ts // ESM import { searchModels, generate } from 'unlimited-ai'; // CJS const { searchModels, generate } = require('unlimited-ai'); const [model] = await searchModels('gpt-4'); const reply = await generate(model, [{ role: 'user', content: 'こんにちは！' }]); ``` キーワードで利用可能なモデル ID をファジー検索し、近い順に返します。 **`word`** `string` 検索キーワード。 **戻り値** `Promise<string[]>` 類似度の高い順に並んだモデル ID。 --- ### `config` ```ts // ESM import { config } from 'unlimited-ai'; // CJS const { config } = require('unlimited-ai'); ``` ```ts console.log(config.API_URL); // https://api.voids.top/v1/chat/completions console.log(config.MODELS_URL); // https://api.voids.top/v1/models ``` 内部で使用している API エンドポイント URL を持つ読み取り専用オブジェクトです。 **`config.API_URL`** `string` チャット補完エンドポイント。デフォルト: `https://api.voids.top/v1/chat/completions` **`config.MODELS_URL`** `string` モデル一覧エンドポイント。デフォルト: `https://api.voids.top/v1/models` --- ## 型定義 ```ts type Role = 'system' | 'user' | 'assistant'; interface Message { role: Role; content: string; } type ConversationStore = Record<string, Message[]>; interface CompletionResponse { id: string; object: string; created: number; model: string; choices: Array<{ index: number; message: { role: string; content: string }; finish_reason: string; }>; usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number }; } interface StreamChunk { id: string; object: string; created: number; model: string; choices: Array<{ index: number; delta: { content?: string; role?: string }; finish_reason: string | null; }>; } ``` --- ## サポート [![Discord](https://discordapp.com/api/guilds/1369635074395344998/widget.png?style=banner2)](https://discord.gg/upSpdDgDha)