Node.js SDK 完整教程

使用 TypeScript 支持的 Node.js SDK 快速集成 LLM API

TypeScript

完整类型支持

流式响应

实时数据流

框架集成

Next.js/Express

异步并发

高性能处理

一、安装配置

快速安装

# 使用 npm 安装
npm install @n1n/llm-api

# 使用 yarn 安装
yarn add @n1n/llm-api

# 使用 pnpm 安装
pnpm add @n1n/llm-api

# TypeScript 类型定义
npm install --save-dev @types/node

二、基础使用

快速开始

import { LLMClient } from '@n1n/llm-api';

// 初始化客户端
const client = new LLMClient({
  apiKey: process.env.LLM_API_KEY,
  baseURL: 'https://api.n1n.ai/v1'
});

// 基础对话
async function chat() {
  try {
    const response = await client.chat.completions.create({
      model: 'gpt-3.5-turbo',
      messages: [
        { role: 'system', content: '你是一个有帮助的助手' },
        { role: 'user', content: '用JavaScript实现快速排序' }
      ],
      temperature: 0.7,
      max_tokens: 500
    });
    
    console.log(response.choices[0].message.content);
    console.log(`Token使用: ${response.usage.total_tokens}`);
    
  } catch (error) {
    console.error('API调用失败:', error);
  }
}

// TypeScript 强类型支持
import { ChatCompletionMessage, ChatCompletionResponse } from '@n1n/llm-api';

interface ConversationParams {
  messages: ChatCompletionMessage[];
  model?: string;
  temperature?: number;
}

async function typedChat(params: ConversationParams): Promise<string> {
  const response: ChatCompletionResponse = await client.chat.completions.create({
    model: params.model || 'gpt-3.5-turbo',
    messages: params.messages,
    temperature: params.temperature || 0.7
  });
  
  return response.choices[0].message.content;
}

三、流式响应处理

实时流输出

import { LLMClient } from '@n1n/llm-api';

const client = new LLMClient({ apiKey: process.env.LLM_API_KEY });

// 流式响应处理
async function streamChat() {
  const stream = await client.chat.completions.create({
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: '写一个故事' }],
    stream: true
  });
  
  // 方式1: for await 循环
  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content || '';
    process.stdout.write(content);
  }
}

// 方式2: 事件监听器
async function streamWithEvents() {
  const stream = await client.chat.completions.create({
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: '解释量子计算' }],
    stream: true
  });
  
  stream.on('content', (content: string) => {
    process.stdout.write(content);
  });
  
  stream.on('error', (error: Error) => {
    console.error('流错误:', error);
  });
  
  stream.on('end', () => {
    console.log('\n流结束');
  });
}

// Express SSE 流式响应
import express from 'express';

const app = express();

app.get('/stream', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  
  const stream = await client.chat.completions.create({
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: req.query.prompt }],
    stream: true
  });
  
  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content || '';
    res.write(`data: ${JSON.stringify({ content })}\n\n`);
  }
  
  res.write('data: [DONE]\n\n');
  res.end();
});

四、高级功能

Function Calling & 批处理

// Function Calling
const response = await client.chat.completions.create({
  model: 'gpt-3.5-turbo',
  messages: [{ role: 'user', content: '北京天气如何？' }],
  functions: [{
    name: 'get_weather',
    description: '获取城市天气',
    parameters: {
      type: 'object',
      properties: {
        location: { type: 'string', description: '城市名' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
      },
      required: ['location']
    }
  }],
  function_call: 'auto'
});

if (response.choices[0].finish_reason === 'function_call') {
  const functionCall = response.choices[0].message.function_call;
  const args = JSON.parse(functionCall.arguments);
  
  // 执行函数
  const weatherData = await getWeather(args.location, args.unit);
  
  // 返回结果给模型
  const finalResponse = await client.chat.completions.create({
    model: 'gpt-3.5-turbo',
    messages: [
      { role: 'user', content: '北京天气如何？' },
      response.choices[0].message,
      {
        role: 'function',
        name: 'get_weather',
        content: JSON.stringify(weatherData)
      }
    ]
  });
}

// 并发批处理
import pLimit from 'p-limit';

const limit = pLimit(5); // 限制并发数为5

async function batchProcess(prompts: string[]) {
  const promises = prompts.map(prompt => 
    limit(() => client.chat.completions.create({
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'user', content: prompt }],
      temperature: 0.3
    }))
  );
  
  const responses = await Promise.all(promises);
  return responses.map(r => r.choices[0].message.content);
}

// 会话管理器
class ConversationManager {
  private messages: ChatCompletionMessage[] = [];
  private maxHistory = 10;
  
  addSystemMessage(content: string) {
    this.messages.push({ role: 'system', content });
  }
  
  async sendMessage(content: string): Promise<string> {
    this.messages.push({ role: 'user', content });
    
    // 保持历史在限制内
    if (this.messages.length > this.maxHistory) {
      const systemMessages = this.messages.filter(m => m.role === 'system');
      const recentMessages = this.messages.slice(-(this.maxHistory - systemMessages.length));
      this.messages = [...systemMessages, ...recentMessages];
    }
    
    const response = await client.chat.completions.create({
      model: 'gpt-3.5-turbo',
      messages: this.messages
    });
    
    const reply = response.choices[0].message;
    this.messages.push(reply);
    
    return reply.content;
  }
}

五、Next.js 集成

App Router API

// app/api/chat/route.ts
import { LLMClient } from '@n1n/llm-api';
import { NextRequest, NextResponse } from 'next/server';

const client = new LLMClient({
  apiKey: process.env.LLM_API_KEY
});

export async function POST(request: NextRequest) {
  try {
    const { messages } = await request.json();
    
    const response = await client.chat.completions.create({
      model: 'gpt-3.5-turbo',
      messages,
      temperature: 0.7
    });
    
    return NextResponse.json({
      content: response.choices[0].message.content,
      usage: response.usage
    });
    
  } catch (error) {
    return NextResponse.json(
      { error: 'API调用失败' },
      { status: 500 }
    );
  }
}

// 流式响应 API
export async function GET(request: NextRequest) {
  const encoder = new TextEncoder();
  const stream = new TransformStream();
  const writer = stream.writable.getWriter();
  
  const prompt = request.nextUrl.searchParams.get('prompt') || '';
  
  // 异步处理流
  (async () => {
    const llmStream = await client.chat.completions.create({
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'user', content: prompt }],
      stream: true
    });
    
    for await (const chunk of llmStream) {
      const content = chunk.choices[0]?.delta?.content || '';
      await writer.write(encoder.encode(`data: ${JSON.stringify({ content })}\n\n`));
    }
    
    await writer.write(encoder.encode('data: [DONE]\n\n'));
    await writer.close();
  })();
  
  return new Response(stream.readable, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive'
    }
  });
}

六、最佳实践

⚡ 性能优化

  • ✅ 使用连接池复用
  • ✅ 实施请求缓存
  • ✅ 批量处理请求
  • ✅ 使用Worker Threads
  • ✅ 流式处理大数据

🔒 安全实践

  • ✅ 环境变量管理密钥
  • ✅ 请求速率限制
  • ✅ 输入验证清理
  • ✅ HTTPS传输加密
  • ✅ 错误信息脱敏

Python SDK

Python集成教程

PHP SDK

PHP集成教程

流式响应

深入了解SSE流