SDK 使用指南

SDK 概述

ZGI 提供多种编程语言的 SDK，帮助开发者快速集成 AI 能力到应用中。

支持的语言

• Node.js (JavaScript/TypeScript)
• Python
• Java
• Go
• PHP

安装说明

Node.js

# 使用 npm
npm install @zgi/sdk

# 使用 yarn
yarn add @zgi/sdk

# 使用 pnpm
pnpm add @zgi/sdk

Python

# 使用 pip
pip install zgi

# 使用 poetry
poetry add zgi

Java

<!-- Maven -->
<dependency>
    <groupId>ai.zgi</groupId>
    <artifactId>zgi-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- Gradle -->
implementation 'ai.zgi:zgi-sdk:1.0.0'

Go

go get github.com/zgi/zgi-go

PHP

composer require zgi/zgi-php

快速开始

Node.js

import { ZGIClient } from '@zgi/sdk';

// 创建客户端实例
const client = new ZGIClient({
    apiKey: 'your-api-key'
});

// 使用对话接口
async function chat() {
    const response = await client.chat.create({
        messages: [{
            role: 'user',
            content: '你好'
        }],
        model: 'zgi-1'
    });
    
    console.log(response.choices[0].message.content);
}

// 使用向量接口
async function embed() {
    const response = await client.embeddings.create({
        text: '示例文本',
        model: 'zgi-embedding-1'
    });
    
    console.log(response.data[0].embedding);
}

Python

from zgi import ZGIClient

# 创建客户端实例
client = ZGIClient(api_key='your-api-key')

# 使用对话接口
def chat():
    response = client.chat.create(
        messages=[{
            'role': 'user',
            'content': '你好'
        }],
        model='zgi-1'
    )
    
    print(response.choices[0].message.content)

# 使用向量接口
def embed():
    response = client.embeddings.create(
        text='示例文本',
        model='zgi-embedding-1'
    )
    
    print(response.data[0].embedding)

Java

import ai.zgi.ZGIClient;
import ai.zgi.model.*;

public class Example {
    public static void main(String[] args) {
        // 创建客户端实例
        ZGIClient client = new ZGIClient("your-api-key");
        
        // 使用对话接口
        ChatResponse response = client.chat()
            .create(ChatRequest.builder()
                .addMessage(new Message("user", "你好"))
                .model("zgi-1")
                .build());
        
        System.out.println(response.getChoices().get(0).getMessage().getContent());
    }
}

高级功能

1. 自定义配置

const client = new ZGIClient({
    apiKey: 'your-api-key',
    baseURL: 'https://api.zgi.ai',
    timeout: 30000,
    maxRetries: 3,
    proxy: {
        host: 'proxy.example.com',
        port: 8080
    }
});

2. 请求拦截器

client.interceptors.request.use(config => {
    // 添加自定义请求头
    config.headers['Custom-Header'] = 'value';
    return config;
});

client.interceptors.response.use(response => {
    // 处理响应数据
    return response;
});

3. 流式响应处理

const stream = await client.chat.create({
    messages: [{
        role: 'user',
        content: '讲个故事'
    }],
    model: 'zgi-1',
    stream: true
});

for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

4. 批量处理

async function batchProcess(texts) {
    const batchSize = 5;
    const results = [];
    
    for (let i = 0; i < texts.length; i += batchSize) {
        const batch = texts.slice(i, i + batchSize);
        const promises = batch.map(text => 
            client.embeddings.create({ text })
        );
        
        const batchResults = await Promise.all(promises);
        results.push(...batchResults);
    }
    
    return results;
}

错误处理

1. 基础错误处理

try {
    const response = await client.chat.create({...});
} catch (error) {
    if (error.response) {
        // API 错误
        console.error(error.response.data);
    } else if (error.request) {
        // 网络错误
        console.error('网络请求失败');
    } else {
        // 其他错误
        console.error('错误:', error.message);
    }
}

2. 重试机制

const client = new ZGIClient({
    apiKey: 'your-api-key',
    maxRetries: 3,
    retryDelay: 1000,
    retryCondition: (error) => {
        return error.response?.status === 429;
    }
});

3. 错误事件监听

client.on('error', error => {
    console.error('API 错误:', error);
});

client.on('retry', (error, retryCount) => {
    console.warn(`重试第 ${retryCount} 次:`, error.message);
});

类型定义

TypeScript 支持

import { ZGIClient, ChatMessage, ChatResponse } from '@zgi/sdk';

async function chat(message: string): Promise<string> {
    const response: ChatResponse = await client.chat.create({
        messages: [{
            role: 'user',
            content: message
        }] as ChatMessage[],
        model: 'zgi-1'
    });
    
    return response.choices[0].message.content;
}

最佳实践

1. 环境配置

// .env
ZGI_API_KEY=your-api-key
ZGI_BASE_URL=https://api.zgi.ai

// config.js
require('dotenv').config();

const client = new ZGIClient({
    apiKey: process.env.ZGI_API_KEY,
    baseURL: process.env.ZGI_BASE_URL
});

2. 日志记录

const winston = require('winston');
const logger = winston.createLogger({
    level: 'info',
    format: winston.format.json(),
    transports: [
        new winston.transports.File({ filename: 'api.log' })
    ]
});

client.on('request', req => {
    logger.info('API请求', {
        method: req.method,
        path: req.path
    });
});

3. 性能优化

// 使用连接池
const client = new ZGIClient({
    apiKey: 'your-api-key',
    pool: {
        maxSockets: 10
    }
});

// 启用压缩
const client = new ZGIClient({
    apiKey: 'your-api-key',
    compression: true
});

常见问题

如何处理大规模请求？

1. 使用批量处理
2. 实现请求队列
3. 控制并发数量
4. 添加错误重试

如何优化性能？

1. 启用连接池
2. 使用压缩
3. 实现缓存
4. 合理设置超时

如何保护 API 密钥？

1. 使用环境变量
2. 避免密钥泄露
3. 定期轮换密钥
4. 设置访问限制

更新日志

v1.1.0 (2024-02-01)

• 添加 TypeScript 类型定义
• 优化错误处理机制
• 增加新的工具函数

v1.0.0 (2024-01-01)

• 首次发布
• 支持基础功能
• 提供完整文档

实际应用场景示例

1. 智能客服系统

// 实现智能客服对话管理
class CustomerService {
    constructor() {
        this.client = new ZGIClient({
            apiKey: process.env.ZGI_API_KEY
        });
        this.conversations = new Map();
    }

    // 处理用户消息
    async handleMessage(userId, message) {
        let conversation = this.conversations.get(userId) || [];
        conversation.push({
            role: 'user',
            content: message
        });

        try {
            const response = await this.client.chat.create({
                model: 'zgi-1',
                messages: conversation,
                temperature: 0.7,
                // 添加系统提示以定制客服风格
                system_message: '你是一位专业、友善的客服代表'
            });

            const reply = response.choices[0].message;
            conversation.push(reply);
            this.conversations.set(userId, conversation);
            return reply.content;
        } catch (error) {
            console.error('客服对话错误:', error);
            return '抱歉，系统暂时无法处理您的请求。';
        }
    }
}

2. 智能内容审核

// 实现内容审核系统
class ContentModerator {
    constructor() {
        this.client = new ZGIClient({
            apiKey: process.env.ZGI_API_KEY
        });
    }

    // 审核文本内容
    async moderateContent(text) {
        try {
            const response = await this.client.chat.create({
                model: 'zgi-1',
                messages: [{
                    role: 'user',
                    content: `请审核以下内容是否包含违规信息：\n${text}`
                }],
                // 使用函数调用获取结构化结果
                functions: [{
                    name: 'content_review',
                    parameters: {
                        type: 'object',
                        properties: {
                            is_appropriate: {
                                type: 'boolean',
                                description: '内容是否合适'
                            },
                            risk_level: {
                                type: 'string',
                                enum: ['low', 'medium', 'high'],
                                description: '风险等级'
                            },
                            reasons: {
                                type: 'array',
                                items: { type: 'string' },
                                description: '风险原因'
                            }
                        }
                    }
                }],
                function_call: { name: 'content_review' }
            });

            return JSON.parse(response.choices[0].message.function_call.arguments);
        } catch (error) {
            console.error('内容审核错误:', error);
            throw new Error('内容审核失败');
        }
    }
}

3. 智能文档搜索

// 实现文档语义搜索
class DocumentSearch {
    constructor() {
        this.client = new ZGIClient({
            apiKey: process.env.ZGI_API_KEY
        });
        this.documents = new Map(); // 存储文档向量
    }

    // 添加文档到搜索系统
    async addDocument(id, content) {
        try {
            const response = await this.client.embeddings.create({
                model: 'zgi-embedding-1',
                text: content
            });

            this.documents.set(id, {
                content,
                embedding: response.data[0].embedding
            });
        } catch (error) {
            console.error('文档向量化错误:', error);
            throw new Error('添加文档失败');
        }
    }

    // 搜索相似文档
    async search(query, limit = 5) {
        try {
            // 获取查询文本的向量
            const queryResponse = await this.client.embeddings.create({
                model: 'zgi-embedding-1',
                text: query
            });
            const queryVector = queryResponse.data[0].embedding;

            // 计算相似度并排序
            const results = Array.from(this.documents.entries())
                .map(([id, doc]) => ({
                    id,
                    content: doc.content,
                    similarity: this.cosineSimilarity(queryVector, doc.embedding)
                }))
                .sort((a, b) => b.similarity - a.similarity)
                .slice(0, limit);

            return results;
        } catch (error) {
            console.error('搜索错误:', error);
            throw new Error('搜索失败');
        }
    }

    // 计算余弦相似度
    cosineSimilarity(vec1, vec2) {
        const dotProduct = vec1.reduce((sum, val, i) => sum + val * vec2[i], 0);
        const norm1 = Math.sqrt(vec1.reduce((sum, val) => sum + val * val, 0));
        const norm2 = Math.sqrt(vec2.reduce((sum, val) => sum + val * val, 0));
        return dotProduct / (norm1 * norm2);
    }
}

4. 多语言翻译服务

// 实现多语言翻译服务
class TranslationService {
    constructor() {
        this.client = new ZGIClient({
            apiKey: process.env.ZGI_API_KEY
        });
    }

    // 翻译文本
    async translate(text, targetLang) {
        try {
            const response = await this.client.chat.create({
                model: 'zgi-1',
                messages: [{
                    role: 'system',
                    content: `你是一个专业的翻译助手，请将文本翻译成${targetLang}，只返回翻译结果。`
                }, {
                    role: 'user',
                    content: text
                }],
                temperature: 0.3 // 降低创造性以确保翻译准确
            });

            return response.choices[0].message.content;
        } catch (error) {
            console.error('翻译错误:', error);
            throw new Error('翻译失败');
        }
    }

    // 批量翻译
    async batchTranslate(texts, targetLang) {
        const batchSize = 5;
        const results = [];

        for (let i = 0; i < texts.length; i += batchSize) {
            const batch = texts.slice(i, i + batchSize);
            const promises = batch.map(text => this.translate(text, targetLang));
            const batchResults = await Promise.all(promises);
            results.push(...batchResults);
        }

        return results;
    }
}

5. 智能数据分析

// 实现数据分析助手
class DataAnalysisAssistant {
    constructor() {
        this.client = new ZGIClient({
            apiKey: process.env.ZGI_API_KEY
        });
    }

    // 分析数据并生成报告
    async analyzeData(data) {
        try {
            const response = await this.client.chat.create({
                model: 'zgi-1',
                messages: [{
                    role: 'system',
                    content: '你是一个专业的数据分析师，请分析数据并生成详细报告。'
                }, {
                    role: 'user',
                    content: `请分析以下数据并提供见解：\n${JSON.stringify(data, null, 2)}`
                }],
                temperature: 0.5,
                max_tokens: 2000
            });

            return response.choices[0].message.content;
        } catch (error) {
            console.error('数据分析错误:', error);
            throw new Error('数据分析失败');
        }
    }

    // 生成数据可视化建议
    async getVisualizationSuggestions(data) {
        try {
            const response = await this.client.chat.create({
                model: 'zgi-1',
                messages: [{
                    role: 'system',
                    content: '你是一个数据可视化专家，请为数据提供可视化建议。'
                }, {
                    role: 'user',
                    content: `请为以下数据提供合适的可视化方案：\n${JSON.stringify(data, null, 2)}`
                }],
                temperature: 0.7
            });

            return response.choices[0].message.content;
        } catch (error) {
            console.error('可视化建议生成错误:', error);
            throw new Error('生成可视化建议失败');
        }
    }
}