ai-world-sdk 1.0.16 → 1.0.17

package/README.md

@@ -47,6 +47,8 @@ const geminiModel = new ChatGoogleGenerativeAI({
   modelName: 'gemini-2.5-flash-image',
   temperature: 0.7,
   provider: 'gemini', // 或 'aihubmix', 'api2img'
+  vertexai: false, // 可选：是否使用 VertexAI（仅当 provider 为 gemini 时有效）
+  jsonSchema: undefined, // 可选：结构化输出 JSON Schema
 });
 
 // GPT 模型（使用 aihubmix provider）
@@ -54,6 +56,7 @@ const gptModel = new ChatOpenAI({
   modelName: 'gpt-4o-mini',
   temperature: 0.7,
   provider: 'aihubmix', // 或 'api2img'
+  jsonSchema: undefined, // 可选：结构化输出 JSON Schema
 });
 
 // Claude 模型（使用 aihubmix provider）
@@ -224,6 +227,9 @@ const model = createChatModel('gemini-2.5-flash-image', {
 - `provider: 'gemini'` - 直接使用 Google Gemini API
 - `provider: 'doubao'` - 使用豆包服务
 
+**结构化输出参数:**
+- `jsonSchema?: Record<string, any>` - JSON Schema 定义，用于结构化输出（使用 `with_structured_output`）
+
 ### 图像生成
 
 #### DoubaoImageGenerationClient
@@ -694,6 +700,101 @@ const response2 = await model.invoke([
 ]);
 ```
 
+### 结构化输出（JSON Schema）
+
+使用 `jsonSchema` 参数可以让模型返回结构化的 JSON 数据，而不是自由文本。
+
+```typescript
+import { ChatOpenAI, ChatGoogleGenerativeAI, HumanMessage, createChatModel } from 'ai-world-sdk';
+
+// 使用 ChatOpenAI 进行结构化输出
+const openaiModel = new ChatOpenAI({
+  modelName: 'gpt-4o-mini',
+  temperature: 0.7,
+  provider: 'aihubmix',
+  jsonSchema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: '用户姓名' },
+      age: { type: 'integer', description: '用户年龄' },
+      email: { type: 'string', description: '用户邮箱' },
+    },
+    required: ['name', 'age'],
+  },
+});
+
+const response = await openaiModel.invoke([
+  new HumanMessage('请提取以下信息：张三，25岁，邮箱是zhangsan@example.com'),
+]);
+
+// 响应内容将是结构化的 JSON 对象
+console.log(response.content); // { name: '张三', age: 25, email: 'zhangsan@example.com' }
+```
+
+**使用 Gemini 模型的结构化输出：**
+
+```typescript
+const geminiModel = new ChatGoogleGenerativeAI({
+  modelName: 'gemini-2.5-flash',
+  temperature: 0.7,
+  provider: 'gemini',
+  jsonSchema: {
+    type: 'object',
+    properties: {
+      summary: { type: 'string', description: '摘要' },
+      keywords: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '关键词列表',
+      },
+      sentiment: {
+        type: 'string',
+        enum: ['positive', 'neutral', 'negative'],
+        description: '情感倾向',
+      },
+    },
+    required: ['summary', 'keywords'],
+  },
+});
+
+const response = await geminiModel.invoke([
+  new HumanMessage("分析这句话的情感：'今天天气真好，心情很愉快！'"),
+]);
+```
+
+**使用 createChatModel 工厂函数：**
+
+```typescript
+const model = createChatModel('gpt-4o-mini', {
+  temperature: 0.7,
+  provider: 'aihubmix',
+  jsonSchema: {
+    type: 'object',
+    properties: {
+      title: { type: 'string', description: '文章标题' },
+      content: { type: 'string', description: '文章内容' },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '标签列表',
+      },
+    },
+    required: ['title', 'content'],
+  },
+});
+
+const response = await model.invoke([
+  new HumanMessage('生成一篇关于人工智能的短文，包含标题、内容和标签'),
+]);
+```
+
+**注意事项：**
+- `jsonSchema` 必须符合 [JSON Schema](https://json-schema.org/) 规范
+- 对于 OpenAI 兼容的模型（如 GPT、Doubao），JSON Schema 会自动添加 `title` 和 `description`（如果缺失）
+- 对于 Gemini 和 Anthropic 模型，直接使用提供的 JSON Schema
+- 结构化输出的响应内容可能是 JSON 字符串或对象，需要根据实际情况解析
+- 结构化输出使用 LangChain 的 `with_structured_output` 方法，底层通过 `method="json_schema"` 实现
+
 ### 流式响应
 
 ```typescript

package/dist/__tests__/example.test.js

@@ -43,6 +43,7 @@ const index_1 = require("../index");
 dotenv.config();
 index_1.sdkConfig.setBaseUrl("http://localhost:8000");
 index_1.sdkConfig.setToken(process.env.AUTH_TOKEN || process.env.TOKEN || "");
+// sdkConfig.setDebug(true);
 function extractTextFromChunk(chunk) {
     if (typeof chunk.content === "string") {
         return chunk.content;
@@ -648,10 +649,10 @@ describe("Langchain SDK Tests", () => {
         });
         const result = await imageClient.generate({
             prompt: 'A beautiful sunset over the ocean',
-            model: 'gemini-3-pro-image-preview',
+            model: 'gemini-2.5-flash-image',
             aspect_ratio: '16:9',
             image_size: '1K',
-            response_modalities: ['IMAGE'], // 仅返回图片
+            response_modalities: ['IMAGE', 'TEXT'],
         });
         expect(result).toBeDefined();
         expect(result.created).toBeDefined();
@@ -713,7 +714,7 @@ describe("Langchain SDK Tests", () => {
             model: 'gemini-3-pro-image-preview',
             aspect_ratio: '16:9',
             image_size: '1K',
-            response_modalities: ['IMAGE'], // 仅返回图片
+            response_modalities: ['IMAGE', 'TEXT'], // 仅返回图片
         });
         expect(result).toBeDefined();
         expect(result.created).toBeDefined();
@@ -1010,4 +1011,160 @@ describe("Langchain SDK Tests", () => {
         }).toThrow("Unsupported model");
         console.log("✅ createChatModel 错误处理测试成功");
     });
+    test("ChatOpenAI - 结构化输出测试", async () => {
+        const openai = new index_1.ChatOpenAI({
+            modelName: "gpt-5.1",
+            temperature: 0.7,
+            provider: "aihubmix",
+            jsonSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "用户姓名" },
+                    age: { type: "integer", description: "用户年龄" },
+                    email: { type: "string", description: "用户邮箱" },
+                },
+                required: ["name", "age"],
+            },
+        });
+        const response = await openai.invoke([
+            new index_1.HumanMessage("请提取以下信息：张三，25岁，邮箱是zhangsan@example.com"),
+        ]);
+        expect(response).toBeDefined();
+        expect(response.content).toBeDefined();
+        // 结构化输出应该返回一个对象
+        const content = response.content;
+        if (typeof content === "string") {
+            // 如果是字符串，尝试解析为 JSON
+            try {
+                const parsed = JSON.parse(content);
+                expect(parsed).toHaveProperty("name");
+                expect(parsed).toHaveProperty("age");
+                expect(typeof parsed.name).toBe("string");
+                expect(typeof parsed.age).toBe("number");
+                console.log("✅ ChatOpenAI 结构化输出测试成功（字符串格式）");
+                console.log("结构化数据:", parsed);
+            }
+            catch (e) {
+                // 如果不是 JSON，至少验证有内容
+                expect(content.length).toBeGreaterThan(0);
+                console.log("✅ ChatOpenAI 结构化输出测试成功（文本格式）");
+                console.log("响应内容:", content);
+            }
+        }
+        else if (typeof content === "object") {
+            // 如果直接是对象
+            expect(content).toHaveProperty("name");
+            expect(content).toHaveProperty("age");
+            console.log("✅ ChatOpenAI 结构化输出测试成功（对象格式）");
+            console.log("结构化数据:", content);
+        }
+        else {
+            console.log("✅ ChatOpenAI 结构化输出测试成功（其他格式）");
+            console.log("响应内容:", content);
+        }
+    }, 30000);
+    test("ChatGoogleGenerativeAI - 结构化输出测试", async () => {
+        const gemini = new index_1.ChatGoogleGenerativeAI({
+            modelName: "gemini-2.5-flash",
+            temperature: 0.7,
+            provider: "gemini",
+            jsonSchema: {
+                type: "object",
+                properties: {
+                    summary: { type: "string", description: "摘要" },
+                    keywords: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "关键词列表",
+                    },
+                    sentiment: {
+                        type: "string",
+                        enum: ["positive", "neutral", "negative"],
+                        description: "情感倾向",
+                    },
+                },
+                required: ["summary", "keywords"],
+            },
+        });
+        const response = await gemini.invoke([
+            new index_1.HumanMessage("分析这句话的情感：'今天天气真好，心情很愉快！'"),
+        ]);
+        expect(response).toBeDefined();
+        expect(response.content).toBeDefined();
+        const content = response.content;
+        if (typeof content === "string") {
+            try {
+                const parsed = JSON.parse(content);
+                expect(parsed).toHaveProperty("summary");
+                expect(parsed).toHaveProperty("keywords");
+                expect(Array.isArray(parsed.keywords)).toBe(true);
+                console.log("✅ ChatGoogleGenerativeAI 结构化输出测试成功（字符串格式）");
+                console.log("结构化数据:", parsed);
+            }
+            catch (e) {
+                expect(content.length).toBeGreaterThan(0);
+                console.log("✅ ChatGoogleGenerativeAI 结构化输出测试成功（文本格式）");
+                console.log("响应内容:", content);
+            }
+        }
+        else if (typeof content === "object") {
+            expect(content).toHaveProperty("summary");
+            expect(content).toHaveProperty("keywords");
+            console.log("✅ ChatGoogleGenerativeAI 结构化输出测试成功（对象格式）");
+            console.log("结构化数据:", content);
+        }
+        else {
+            console.log("✅ ChatGoogleGenerativeAI 结构化输出测试成功（其他格式）");
+            console.log("响应内容:", content);
+        }
+    }, 30000);
+    test("createChatModel - 结构化输出测试", async () => {
+        const model = (0, index_1.createChatModel)("gpt-5.1", {
+            temperature: 0.7,
+            provider: "aihubmix",
+            jsonSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string", description: "文章标题" },
+                    content: { type: "string", description: "文章内容" },
+                    tags: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "标签列表",
+                    },
+                },
+                required: ["title", "content"],
+            },
+        });
+        const response = await model.invoke([
+            new index_1.HumanMessage("生成一篇关于人工智能的短文，包含标题、内容和标签"),
+        ]);
+        expect(response).toBeDefined();
+        expect(response.content).toBeDefined();
+        const content = response.content;
+        if (typeof content === "string") {
+            try {
+                const parsed = JSON.parse(content);
+                expect(parsed).toHaveProperty("title");
+                expect(parsed).toHaveProperty("content");
+                console.log("✅ createChatModel 结构化输出测试成功（字符串格式）");
+                console.log("结构化数据:", parsed);
+            }
+            catch (e) {
+                expect(content.length).toBeGreaterThan(0);
+                console.log("✅ createChatModel 结构化输出测试成功（文本格式）");
+                console.log("响应内容:", content);
+            }
+        }
+        else if (typeof content === "object") {
+            expect(content).toHaveProperty("title");
+            expect(content).toHaveProperty("content");
+            console.log("✅ createChatModel 结构化输出测试成功（对象格式）");
+            console.log("结构化数据:", content);
+        }
+        else {
+            console.log("✅ createChatModel 结构化输出测试成功（其他格式）");
+            console.log("响应内容:", content);
+        }
+    }, 30000);
 });

package/dist/base.d.ts

@@ -13,6 +13,8 @@ export interface BaseChatModelParams {
     topP?: number;
     modelName?: string;
     apiKey?: string;
+    vertexai?: boolean;
+    jsonSchema?: Record<string, any>;
 }
 export interface ChatResult {
     content: string;
@@ -47,6 +49,8 @@ export declare abstract class BaseChatModel {
     protected boundOptions?: BindOptions;
     protected provider: string;
     protected apiKey?: string;
+    protected vertexai?: boolean;
+    protected jsonSchema?: Record<string, any>;
     constructor(config: {
         baseUrl?: string;
         headers?: Record<string, string>;
@@ -56,6 +60,8 @@ export declare abstract class BaseChatModel {
         modelName: string;
         provider: AIModelProvider;
         apiKey?: string;
+        vertexai?: boolean;
+        jsonSchema?: Record<string, any>;
     });
     /**
      * Invoke the model with messages (non-streaming)

package/dist/base.js

@@ -14,13 +14,15 @@ class BaseChatModel {
         const globalHeaders = config_1.sdkConfig.getHeaders();
         this.headers = {
             "Content-Type": "application/json",
-            "Authorization": `Bearer ${config_1.sdkConfig.getToken()}`,
+            Authorization: `Bearer ${config_1.sdkConfig.getToken()}`,
             "X-Base-Url": config.baseUrl || "",
             ...globalHeaders,
             ...config.headers,
         };
         this.provider = config.provider;
         this.apiKey = config.apiKey;
+        this.vertexai = config.vertexai;
+        this.jsonSchema = config.jsonSchema;
         this.temperature = config.temperature ?? 0.7;
         this.maxTokens = config.maxTokens;
         this.topP = config.topP;
@@ -45,6 +47,14 @@ class BaseChatModel {
             provider: this.provider,
             api_key_env: this.apiKey,
         };
+        // 添加 vertexai 参数（仅当 provider 为 gemini 时有效）
+        if (this.provider === "gemini" && this.vertexai !== undefined) {
+            requestBody.vertexai = this.vertexai;
+        }
+        // 添加 response_schema 参数
+        if (this.jsonSchema) {
+            requestBody.response_schema = this.jsonSchema;
+        }
         const url = `${config_1.sdkConfig.getServerUrl()}/api/langchain-proxy/invoke`;
         (0, log_1.logRequest)("POST", url, this.headers, requestBody);
         const response = await fetch(url, {
@@ -60,6 +70,9 @@ class BaseChatModel {
         // 返回标准 AIMessage 格式（从 message_to_dict 序列化）
         const data = (await response.json());
         (0, log_1.logResponse)(response.status, response.statusText, response.headers, data);
+        if (this.jsonSchema) {
+            return new messages_1.AIMessage(data);
+        }
         // 从标准 AIMessage 格式创建 AIMessage 对象
         const content = data.content || "";
         return new messages_1.AIMessage(content);
@@ -83,6 +96,14 @@ class BaseChatModel {
             provider: this.provider,
             api_key_env: this.apiKey,
         };
+        // 添加 vertexai 参数（仅当 provider 为 gemini 时有效）
+        if (this.provider === "gemini" && this.vertexai !== undefined) {
+            requestBody.vertexai = this.vertexai;
+        }
+        // 添加 response_schema 参数
+        if (this.jsonSchema) {
+            requestBody.response_schema = this.jsonSchema;
+        }
         const url = `${config_1.sdkConfig.getServerUrl()}/api/langchain-proxy/stream`;
         const streamHeaders = {
             ...this.headers,
@@ -143,6 +164,14 @@ class BaseChatModel {
             provider: this.provider,
             api_key_env: this.apiKey,
         };
+        // 添加 vertexai 参数（仅当 provider 为 gemini 时有效）
+        if (this.provider === "gemini" && this.vertexai !== undefined) {
+            requestBody.vertexai = this.vertexai;
+        }
+        // 添加 response_schema 参数
+        if (this.jsonSchema) {
+            requestBody.response_schema = this.jsonSchema;
+        }
         const url = `${config_1.sdkConfig.getServerUrl()}/api/langchain-proxy/batch`;
         (0, log_1.logRequest)("POST", url, this.headers, requestBody);
         const response = await fetch(url, {

package/dist/gemini-image-generation.d.ts

@@ -7,11 +7,13 @@ export interface GeminiImageGenerationConfig {
     provider?: GeminiImageGenerationProvider;
     baseUrl?: string;
     headers?: Record<string, string>;
+    vertexai?: boolean;
 }
 export interface GeminiImageGenerationRequest {
     prompt: string;
     model?: string;
     image?: string | string[];
+    vertexai?: boolean;
     aspect_ratio?: "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "4:5" | "5:4" | "9:16" | "16:9" | "21:9";
     image_size?: "1K" | "2K" | "4K";
     temperature?: number;
@@ -34,6 +36,7 @@ export interface GeminiImageChatRequest {
     chat_id?: string;
     model?: string;
     provider?: GeminiImageGenerationProvider;
+    vertexai?: boolean;
     aspect_ratio?: "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "4:5" | "5:4" | "9:16" | "16:9" | "21:9";
     image_size?: "1K" | "2K" | "4K";
     response_modalities?: ("TEXT" | "IMAGE")[];
@@ -48,6 +51,7 @@ export interface GeminiImageChatResponse {
 export declare class GeminiImageGenerationClient {
     private headers;
     private provider;
+    private vertexai?;
     constructor(config?: GeminiImageGenerationConfig);
     /**
      * Generate images

package/dist/gemini-image-generation.js

@@ -11,6 +11,7 @@ class GeminiImageGenerationClient {
     constructor(config) {
         // 确定 provider（默认为 gemini）
         this.provider = config?.provider || "gemini";
+        this.vertexai = config?.vertexai;
         // 合并全局 headers 和配置 headers
         const globalHeaders = config_1.sdkConfig.getHeaders();
         this.headers = {
@@ -62,6 +63,12 @@ class GeminiImageGenerationClient {
         if (request.user) {
             requestBody.user = request.user;
         }
+        if (request.vertexai !== undefined && this.provider === "gemini") {
+            requestBody.vertexai = request.vertexai;
+        }
+        else if (this.vertexai !== undefined && this.provider === "gemini") {
+            requestBody.vertexai = this.vertexai;
+        }
         const url = `${config_1.sdkConfig.getServerUrl()}/api/gemini-image-proxy/generate`;
         (0, log_1.logRequest)("POST", url, this.headers, requestBody);
         const response = await fetch(url, {
@@ -129,6 +136,12 @@ class GeminiImageGenerationClient {
         if (request.provider) {
             requestBody.provider = request.provider;
         }
+        if (request.vertexai !== undefined && (request.provider === "gemini" || this.provider === "gemini")) {
+            requestBody.vertexai = request.vertexai;
+        }
+        else if (this.vertexai !== undefined && this.provider === "gemini") {
+            requestBody.vertexai = this.vertexai;
+        }
         const url = `${config_1.sdkConfig.getServerUrl()}/api/gemini-image-proxy/chat`;
         (0, log_1.logRequest)("POST", url, this.headers, requestBody);
         const response = await fetch(url, {

package/dist/messages.d.ts

@@ -8,7 +8,7 @@ export interface MessageContent {
     image_url?: string;
 }
 export interface BaseMessage {
-    content: string | MessageContent[];
+    content: string | MessageContent[] | Record<string, any>;
     role?: "user" | "assistant" | "system";
 }
 export declare class HumanMessage implements BaseMessage {
@@ -17,9 +17,9 @@ export declare class HumanMessage implements BaseMessage {
     constructor(content: string | MessageContent[]);
 }
 export declare class AIMessage implements BaseMessage {
-    content: string | MessageContent[];
+    content: string | MessageContent[] | Record<string, any>;
     role: "assistant";
-    constructor(content: string | MessageContent[]);
+    constructor(content: string | MessageContent[] | Record<string, any>);
 }
 export declare class SystemMessage implements BaseMessage {
     content: string | MessageContent[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-world-sdk",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "TypeScript SDK for AI World Platform - Chat Models, Image Generation, and Video Generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",