create-entity-app-server 0.0.3

package/src/app/plugins/llm/providers/azure.ts

@@ -0,0 +1,267 @@
+/**
+ * LLM 클라이언트 — Azure OpenAI 드라이버
+ *
+ * Azure OpenAI Service와의 차이점:
+ *  - 인증: `Authorization: Bearer` 대신 `api-key: <key>` 헤더 사용
+ *  - URL 구조: `<base_url>/openai/deployments/<model>/chat/completions?api-version=<version>`
+ *  - 임베딩 URL: `<base_url>/openai/deployments/<embed_model>/embeddings?api-version=<version>`
+ *
+ * 설정 예시:
+ *  {
+ *    "driver": "azure_openai",
+ *    "api_key": "${LLM_AZURE_API_KEY}",
+ *    "base_url": "https://<resource>.openai.azure.com",
+ *    "model": "<chat-deployment-name>",
+ *    "embed_model": "<embedding-deployment-name>",
+ *    "api_version": "2024-12-01-preview",
+ *    "max_tokens": 4096,
+ *    "temperature": 0.1
+ *  }
+ */
+
+import type {
+    LlmClient,
+    LlmProviderConfig,
+    ChatRequest,
+    ChatResponse,
+    StreamChunk,
+    EmbedRequest,
+    EmbedResponse,
+} from "../types/index.ts";
+
+export class AzureOpenAIClient implements LlmClient {
+    private readonly cfg: LlmProviderConfig;
+    private readonly baseURL: string;
+    private readonly apiVersion: string;
+    private readonly timeout: number;
+
+    constructor(cfg: LlmProviderConfig) {
+        this.cfg = cfg;
+        this.baseURL = (cfg.base_url ?? "").replace(/\/+$/, "");
+        this.apiVersion = cfg.api_version ?? "2024-12-01-preview";
+        this.timeout = (cfg.timeout_sec ?? 60) * 1000;
+    }
+
+    name(): string {
+        return "azure_openai";
+    }
+
+    close(): void {
+        /* no-op */
+    }
+
+    // ─── Chat ────────────────────────────────────────────────────────────
+
+    async chat(req: ChatRequest, signal?: AbortSignal): Promise<ChatResponse> {
+        const body = this.buildBody(req, false);
+        const resp = await this.doRequest(
+            "chat/completions",
+            this.cfg.model,
+            body,
+            signal,
+        );
+
+        const choice = resp.choices?.[0];
+        const chatResp: ChatResponse = {
+            content: choice?.message?.content ?? "",
+            finishReason: choice?.finish_reason ?? "",
+            model: resp.model ?? this.cfg.model,
+        };
+
+        if (resp.usage) {
+            chatResp.usage = {
+                promptTokens: resp.usage.prompt_tokens ?? 0,
+                completionTokens: resp.usage.completion_tokens ?? 0,
+                totalTokens: resp.usage.total_tokens ?? 0,
+            };
+        }
+
+        return chatResp;
+    }
+
+    // ─── Stream ──────────────────────────────────────────────────────────
+
+    async *chatStream(
+        req: ChatRequest,
+        signal?: AbortSignal,
+    ): AsyncGenerator<StreamChunk> {
+        const body = this.buildBody(req, true);
+        const url = this.buildURL("chat/completions", this.cfg.model);
+
+        const response = await fetch(url, {
+            method: "POST",
+            headers: this.buildHeaders(),
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeout),
+        });
+
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(
+                `Azure OpenAI stream: status ${response.status}: ${text}`,
+            );
+        }
+
+        const reader = response.body!.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop()!;
+
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed.startsWith("data: ")) continue;
+                    const data = trimmed.slice(6);
+                    if (data === "[DONE]") {
+                        yield { content: "", done: true };
+                        return;
+                    }
+
+                    try {
+                        const event = JSON.parse(data);
+                        const delta = event.choices?.[0]?.delta;
+                        const finishReason = event.choices?.[0]?.finish_reason;
+                        const isDone =
+                            finishReason != null && finishReason !== "";
+
+                        const chunk: StreamChunk = {
+                            content: delta?.content ?? "",
+                            done: isDone,
+                        };
+
+                        if (isDone) chunk.finishReason = finishReason;
+                        if (event.usage) {
+                            chunk.usage = {
+                                promptTokens: event.usage.prompt_tokens ?? 0,
+                                completionTokens:
+                                    event.usage.completion_tokens ?? 0,
+                                totalTokens: event.usage.total_tokens ?? 0,
+                            };
+                        }
+
+                        yield chunk;
+                        if (isDone) return;
+                    } catch {
+                        // JSON parse 실패 — 무시
+                    }
+                }
+            }
+        } finally {
+            reader.releaseLock();
+        }
+    }
+
+    // ─── Embed ───────────────────────────────────────────────────────────
+
+    async embed(
+        req: EmbedRequest,
+        signal?: AbortSignal,
+    ): Promise<EmbedResponse> {
+        const deployment = req.model || this.cfg.embed_model || this.cfg.model;
+        const body = { input: req.input, model: deployment };
+
+        const resp = await this.doRequest(
+            "embeddings",
+            deployment,
+            body,
+            signal,
+        );
+
+        const embeddings: number[][] = (resp.data ?? []).map(
+            (d: { embedding: number[] }) => d.embedding,
+        );
+
+        return {
+            embeddings,
+            model: resp.model ?? deployment,
+            totalTokens: resp.usage?.total_tokens ?? 0,
+        };
+    }
+
+    // ─── Internal ────────────────────────────────────────────────────────
+
+    /** Azure 전용 인증 헤더를 구성한다 (api-key) */
+    private buildHeaders(): Record<string, string> {
+        const h: Record<string, string> = {
+            "Content-Type": "application/json",
+        };
+        if (this.cfg.api_key) {
+            h["api-key"] = this.cfg.api_key;
+        }
+        return h;
+    }
+
+    /**
+     * Azure 엔드포인트 URL을 구성한다.
+     * 형식: `<base_url>/openai/deployments/<deployment>/<operation>?api-version=<version>`
+     */
+    private buildURL(operation: string, deployment: string): string {
+        return `${this.baseURL}/openai/deployments/${deployment}/${operation}?api-version=${this.apiVersion}`;
+    }
+
+    /** 요청 바디를 구성한다 */
+    private buildBody(
+        req: ChatRequest,
+        stream: boolean,
+    ): Record<string, unknown> {
+        const messages: Array<{ role: string; content: string }> = [];
+
+        if (req.system) {
+            messages.push({ role: "system", content: req.system });
+        }
+        for (const m of req.messages) {
+            messages.push({ role: m.role, content: m.content });
+        }
+
+        // Azure는 body에 model 필드 불필요 (deployment가 URL에 포함됨)
+        const body: Record<string, unknown> = { messages, stream };
+
+        const temp = req.temperature ?? this.cfg.temperature;
+        if (temp != null && temp > 0) body.temperature = temp;
+
+        const maxTokens = req.maxTokens ?? this.cfg.max_tokens;
+        if (maxTokens != null && maxTokens > 0) body.max_tokens = maxTokens;
+
+        const topP = req.topP ?? this.cfg.top_p;
+        if (topP != null && topP > 0) body.top_p = topP;
+
+        if (req.jsonMode || this.cfg.json_mode) {
+            body.response_format = { type: "json_object" };
+        }
+
+        if (req.stop?.length) body.stop = req.stop;
+        if (stream) body.stream_options = { include_usage: true };
+
+        return body;
+    }
+
+    /** API 요청을 실행하고 응답을 파싱한다 */
+    private async doRequest(
+        operation: string,
+        deployment: string,
+        body: unknown,
+        signal?: AbortSignal,
+    ): Promise<any> {
+        const url = this.buildURL(operation, deployment);
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: this.buildHeaders(),
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeout),
+        });
+
+        const text = await resp.text();
+        if (!resp.ok) {
+            throw new Error(`Azure OpenAI: status ${resp.status}: ${text}`);
+        }
+
+        return JSON.parse(text);
+    }
+}

package/src/app/plugins/llm/providers/gemini.ts

@@ -0,0 +1,252 @@
+/**
+ * LLM 클라이언트 — Google Gemini 드라이버
+ *
+ * Gemini REST API (generateContent / streamGenerateContent) 호출
+ */
+
+import type {
+    LlmClient,
+    LlmProviderConfig,
+    ChatRequest,
+    ChatResponse,
+    StreamChunk,
+    EmbedRequest,
+    EmbedResponse,
+} from "../types/index.ts";
+
+export class GeminiClient implements LlmClient {
+    private readonly cfg: LlmProviderConfig;
+    private readonly baseURL: string;
+    private readonly timeout: number;
+
+    /** GeminiClient 인스턴스를 초기화한다 */
+    constructor(cfg: LlmProviderConfig) {
+        this.cfg = cfg;
+        this.baseURL = (
+            cfg.base_url || "https://generativelanguage.googleapis.com/v1beta"
+        ).replace(/\/+$/, "");
+        this.timeout = (cfg.timeout_sec || 30) * 1000;
+    }
+
+    /** 프로바이더 이름을 반환한다 */
+    name(): string {
+        return "gemini";
+    }
+
+    /** 클라이언트 리소스를 정리한다 */
+    close(): void {
+        /* no-op */
+    }
+
+    // ─── Chat ────────────────────────────────────────────────────────────
+
+    /** 채팅 완성 API를 호출한다 */
+    async chat(req: ChatRequest, signal?: AbortSignal): Promise<ChatResponse> {
+        const body = this.buildBody(req);
+        const url = `${this.baseURL}/models/${this.cfg.model}:generateContent?key=${this.cfg.api_key}`;
+
+        const resp = await this.doRequest(url, body, signal);
+
+        const candidate = resp.candidates?.[0];
+        const content =
+            candidate?.content?.parts
+                ?.map((p: { text?: string }) => p.text ?? "")
+                .join("") ?? "";
+
+        const chatResp: ChatResponse = {
+            content,
+            finishReason: candidate?.finishReason ?? "",
+            model: this.cfg.model,
+        };
+
+        if (resp.usageMetadata) {
+            chatResp.usage = {
+                promptTokens: resp.usageMetadata.promptTokenCount ?? 0,
+                completionTokens: resp.usageMetadata.candidatesTokenCount ?? 0,
+                totalTokens: resp.usageMetadata.totalTokenCount ?? 0,
+            };
+        }
+
+        return chatResp;
+    }
+
+    // ─── Stream ──────────────────────────────────────────────────────────
+
+    /** 스트리밍 채팅 API를 호출한다 */
+    async *chatStream(
+        req: ChatRequest,
+        signal?: AbortSignal,
+    ): AsyncGenerator<StreamChunk> {
+        const body = this.buildBody(req);
+        const url = `${this.baseURL}/models/${this.cfg.model}:streamGenerateContent?key=${this.cfg.api_key}&alt=sse`;
+
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeout),
+        });
+
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(
+                `Gemini stream: status ${response.status}: ${text}`,
+            );
+        }
+
+        const reader = response.body!.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop()!;
+
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed.startsWith("data: ")) continue;
+
+                    try {
+                        const event = JSON.parse(trimmed.slice(6));
+                        const candidate = event.candidates?.[0];
+                        const text =
+                            candidate?.content?.parts
+                                ?.map((p: { text?: string }) => p.text ?? "")
+                                .join("") ?? "";
+                        const finishReason = candidate?.finishReason;
+                        const isDone =
+                            finishReason === "STOP" ||
+                            finishReason === "MAX_TOKENS";
+
+                        const chunk: StreamChunk = {
+                            content: text,
+                            done: isDone,
+                        };
+
+                        if (isDone) {
+                            chunk.finishReason = finishReason;
+                        }
+                        if (event.usageMetadata) {
+                            chunk.usage = {
+                                promptTokens:
+                                    event.usageMetadata.promptTokenCount ?? 0,
+                                completionTokens:
+                                    event.usageMetadata.candidatesTokenCount ??
+                                    0,
+                                totalTokens:
+                                    event.usageMetadata.totalTokenCount ?? 0,
+                            };
+                        }
+
+                        yield chunk;
+                        if (isDone) return;
+                    } catch {
+                        // JSON parse 실패 — 무시
+                    }
+                }
+            }
+        } finally {
+            reader.releaseLock();
+        }
+    }
+
+    // ─── Embed ───────────────────────────────────────────────────────────
+
+    /** 텍스트 임베딩 API를 호출한다 */
+    async embed(
+        req: EmbedRequest,
+        signal?: AbortSignal,
+    ): Promise<EmbedResponse> {
+        const model = req.model || this.cfg.embed_model || this.cfg.model;
+        const url = `${this.baseURL}/models/${model}:embedContent?key=${this.cfg.api_key}`;
+
+        // Gemini는 단일 텍스트 임베딩만 지원 → 배치 처리
+        const embeddings: number[][] = [];
+        let totalTokens = 0;
+
+        for (const text of req.input) {
+            const body = {
+                model: `models/${model}`,
+                content: { parts: [{ text }] },
+            };
+
+            const resp = await this.doRequest(url, body, signal);
+            if (resp.embedding?.values) {
+                embeddings.push(resp.embedding.values);
+            }
+        }
+
+        return {
+            embeddings,
+            model,
+            totalTokens,
+        };
+    }
+
+    // ─── Internal ────────────────────────────────────────────────────────
+
+    /** 요청 바디를 구성한다 */
+    private buildBody(req: ChatRequest): Record<string, unknown> {
+        const contents: Array<{
+            role: string;
+            parts: Array<{ text: string }>;
+        }> = [];
+
+        // Gemini는 system role을 직접 지원하지 않으므로 user/model 쌍으로 변환
+        if (req.system) {
+            contents.push({ role: "user", parts: [{ text: req.system }] });
+            contents.push({ role: "model", parts: [{ text: "Understood." }] });
+        }
+
+        for (const m of req.messages) {
+            const role = m.role === "assistant" ? "model" : m.role;
+            contents.push({ role, parts: [{ text: m.content }] });
+        }
+
+        const body: Record<string, unknown> = { contents };
+
+        const generationConfig: Record<string, unknown> = {};
+        const temp = req.temperature ?? this.cfg.temperature;
+        if (temp != null && temp > 0) generationConfig.temperature = temp;
+
+        const maxTokens = req.maxTokens ?? this.cfg.max_tokens;
+        if (maxTokens != null && maxTokens > 0)
+            generationConfig.maxOutputTokens = maxTokens;
+
+        if (req.jsonMode || this.cfg.json_mode) {
+            generationConfig.responseMimeType = "application/json";
+        }
+
+        if (Object.keys(generationConfig).length > 0) {
+            body.generationConfig = generationConfig;
+        }
+
+        return body;
+    }
+
+    /** API 요청을 실행하고 응답을 파싱한다 */
+    private async doRequest(
+        url: string,
+        body: unknown,
+        signal?: AbortSignal,
+    ): Promise<any> {
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeout),
+        });
+
+        const text = await resp.text();
+        if (!resp.ok) {
+            throw new Error(`Gemini: status ${resp.status}: ${text}`);
+        }
+
+        return JSON.parse(text);
+    }
+}

package/src/app/plugins/llm/providers/index.ts

@@ -0,0 +1,86 @@
+/**
+ * LLM 클라이언트 팩토리
+ *
+ * driver 이름에 따라 적절한 LlmClient 구현체를 생성합니다.
+ *
+ * ── 클라우드 (OpenAI 호환 API) ──────────────────────────────────────────────
+ *  openai              — OpenAI (https://api.openai.com)
+ *  groq                — Groq 초고속 추론 (https://api.groq.com/openai/v1)
+ *  together            — Together.ai (https://api.together.xyz/v1)
+ *  deepseek            — DeepSeek (https://api.deepseek.com/v1)
+ *  mistral             — Mistral AI (https://api.mistral.ai/v1)
+ *  perplexity          — Perplexity AI (https://api.perplexity.ai)
+ *
+ * ── 클라우드 (전용 API 드라이버) ─────────────────────────────────────────────
+ *  anthropic           — Anthropic Claude
+ *  gemini              — Google Gemini
+ *  azure_openai        — Azure OpenAI (api-key 헤더 + Azure URL 구조)
+ *
+ * ── 로컬 런타임 (OpenAI 호환 HTTP API) ──────────────────────────────────────
+ *  ollama              — Ollama (:11434) — 자체 프로토콜 드라이버
+ *  vllm                — vLLM (:8000)
+ *  localai             — LocalAI (:8080)
+ *  lmstudio            — LM Studio (:1234)
+ *  llamacpp            — llama.cpp server (:8080)
+ *  koboldcpp           — KoboldCpp (:5001)
+ *  text_generation_webui — Text Generation WebUI / oobabooga (:5000)
+ *  jan                 — Jan Desktop (:1337)
+ *  xinference          — Xinference (:9997)
+ *  tabbyapi            — TabbyAPI / ExLlamaV2 (:5000)
+ *  openwebui           — Open WebUI 프록시 (:3000)
+ */
+
+import type { LlmClient, LlmProviderConfig } from "../types/index.ts";
+import { OpenAIClient } from "./openai.ts";
+import { AnthropicClient } from "./anthropic.ts";
+import { GeminiClient } from "./gemini.ts";
+import { OllamaClient } from "./ollama.ts";
+import { AzureOpenAIClient } from "./azure.ts";
+
+/** OpenAI 호환 API를 사용하는 드라이버 목록 */
+const OPENAI_COMPATIBLE_DRIVERS = new Set([
+    // 클라우드
+    "openai",
+    "groq",
+    "together",
+    "deepseek",
+    "mistral",
+    "perplexity",
+    // 로컬 런타임
+    "vllm",
+    "localai",
+    "lmstudio",
+    "llamacpp",
+    "koboldcpp",
+    "text_generation_webui",
+    "jan",
+    "xinference",
+    "tabbyapi",
+    "openwebui",
+]);
+
+/**
+ * 프로바이더 설정으로 LlmClient 인스턴스를 생성합니다.
+ *
+ * @throws driver가 지원하지 않는 값이면 Error
+ */
+export function createClient(cfg: LlmProviderConfig): LlmClient {
+    const driver = cfg.driver.toLowerCase();
+
+    if (OPENAI_COMPATIBLE_DRIVERS.has(driver)) {
+        return new OpenAIClient(cfg);
+    }
+
+    switch (driver) {
+        case "anthropic":
+            return new AnthropicClient(cfg);
+        case "gemini":
+            return new GeminiClient(cfg);
+        case "ollama":
+            return new OllamaClient(cfg);
+        case "azure_openai":
+            return new AzureOpenAIClient(cfg);
+        default:
+            throw new Error(`Unsupported LLM driver: ${cfg.driver}`);
+    }
+}