云信AI部署

TypeScript开发者的LocalAI入门到精通指南 (2025年05月)

云信安装大师
90
AI 质量分
10 5 月, 2025
4 分钟阅读
0 阅读

TypeScript开发者的LocalAI入门到精通指南 (2025年05月)

引言

LocalAI是一个强大的本地AI运行环境，允许开发者在自己的机器上运行各种开源AI模型。对于TypeScript开发者来说，掌握LocalAI可以让你在不依赖云服务的情况下构建智能应用。本文将带你从零开始学习如何在TypeScript项目中集成和使用LocalAI。

准备工作

在开始之前，请确保你的开发环境满足以下要求：

  • Node.js 18+ (推荐使用最新LTS版本)
  • TypeScript 5.0+
  • Docker (用于运行LocalAI容器)
  • 至少16GB内存 (运行大型模型需要)
代码片段 
# 检查Node.js和npm版本
node -v
npm -v

# 检查TypeScript版本
tsc -v

第一步：安装和配置LocalAI

1.1 使用Docker运行LocalAI

最简单的方式是通过Docker容器运行LocalAI：

代码片段 
# 拉取最新版LocalAI镜像
docker pull quay.io/go-skynet/localai:latest

# 运行LocalAI容器
docker run -p 8080:8080 -v $PWD/models:/models -e MODELS_PATH=/models quay.io/go-skynet/localai:latest --models-path /models --context-size 700 --threads 4

参数说明：
– -p 8080:8080：将容器的8080端口映射到主机
– -v $PWD/models:/models：挂载本地models目录到容器
– --context-size：设置模型的上下文大小
– --threads：设置使用的CPU线程数

1.2 验证安装

访问 http://localhost:8080，你应该能看到LocalAI的欢迎页面。

第二步：下载模型

LocalAI支持多种开源模型。让我们下载一个适合TypeScript开发者使用的模型：

代码片段 
# 创建models目录（如果不存在）
mkdir -p models

# 下载ggml格式的模型（以gpt4all为例）
wget https://gpt4all.io/models/ggml-gpt4all-j-v1.3-groovy.bin -O models/ggml-gpt4all-j-v1.3-groovy.bin

注意事项：
1. 模型文件通常较大(几个GB)，请确保有足够的磁盘空间
2. 根据你的硬件选择合适的模型大小

第三步：创建TypeScript项目

3.1 初始化项目

代码片段 
mkdir localai-typescript-demo
cd localai-typescript-demo
npm init -y
npm install typescript @types/node --save-dev
npx tsc --init

3.2 安装必要的依赖

代码片段 
npm install axios dotenv openai-api-like-client --save

第四步：编写TypeScript客户端

创建一个 src/index.ts 文件：

代码片段 
import axios from 'axios';
import * as dotenv from 'dotenv';

// 加载环境变量
dotenv.config();

// LocalAI配置接口
interface LocalAIConfig {
    apiKey?: string;
    baseUrl?: string;
    model?: string;
}

// LocalAI客户端类
class LocalAIClient {
    private config: LocalAIConfig;

    constructor(config: LocalAIConfig = {}) {
        this.config = {
            apiKey: process.env.LOCAL_AI_API_KEY || config.apiKey || '',
            baseUrl: process.env.LOCAL_AI_BASE_URL || config.baseUrl || 'http://localhost:8080',
            model: process.env.LOCAL_AI_MODEL || config.model || 'ggml-gpt4all-j-v1.3-groovy'
        };
    }

    // AI补全方法
    async complete(prompt: string, maxTokens = 128): Promise<string> {
        try {
            const response = await axios.post(`${this.config.baseUrl}/v1/completions`, {
                model: this.config.model,
                prompt,
                max_tokens: maxTokens,
                temperature: 0.7,
            }, {
                headers: {
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${this.config.apiKey}`
                }
            });

            return response.data.choices[0].text.trim();
        } catch (error) {
            console.error('Error calling LocalAI:', error);
            throw error;
        }
    }

    // AI聊天方法（更高级的交互）
    async chat(messages: Array<{role: string, content: string}>, maxTokens = &128): Promise<string> {
        try {
            const response = await axios.post(`${this.config.baseUrl}/v1/chat/completions`, {
                model: this.config.model,
                messages,
                max_tokens: maxTokens,
                temperature: &0.7,
            }, { 
                headers: { 
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${this.config.apiKey}`
                }
            });

            return response.data.choices[0].message.content.trim();
        } catch (error) {
            console.error('Error calling LocalAI:', error);
            throw error;
        }
    }
}

// Example usage:
(async () => {
    const localAI = new LocalAIClient();

    // Simple completion example:
    const completionResult = await localAI.complete("Explain TypeScript generics in simple terms:");
    console.log("Completion Result:", completionResult);

    // Chat example:
    const chatResult = await localAI.chat([
        { role: "system", content: "You are a helpful TypeScript coding assistant." },
        { role: "user", content: "How do I declare a typed array in TypeScript?" }
    ]);

    console.log("Chat Result:", chatResult);
})();

代码说明：
1. LocalAIClient类封装了与LocalAPI交互的核心逻辑
2. complete方法适用于简单的文本补全任务
3. chat方法支持更复杂的对话式交互
4. API设计兼容OpenAI风格，便于迁移

第五步：编译和运行

5.1 tsconfig.json配置

确保你的tsconfig.json包含以下关键配置：

代码片段 
{
"compilerOptions": {  
"target": "ES2022",
"module": "CommonJS",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true  
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}

&5.2 Build and Run

代码片段 
npx tsc && node dist/index.js

Advanced Topics

Model Fine-tuning

To fine-tune models for your specific use case:

代码片段 
# Prepare training data (JSONL format)  
echo '{"prompt":"What is TypeScript?","completion":"TypeScript is a strongly typed..."}' > training_data.jsonl  

# Start fine-tuning  
curl -X POST "http://localhost:8080/v1/fine-tunes" \  
-H "Content-Type: application/json" \  
-d '{  
"training_file": "training_data.jsonl",  
"model": "ggml-gpt4all-j-v1.3-groovy",  
"suffix": "typescript-specialist" 
}'

Performance Optimization

Add these parameters when starting the container for better performance:

代码片段 
docker run ... --cpuset-cpus=0-3 --gpus all ... # Limit CPUs and enable GPU acceleration

Common Issues & Solutions

Issue: Model not loading properly
Solution: Check the logs with docker logs <container_id> and ensure:
– Model file is in the correct format (.bin or .gguf)
– Model file is in the mounted /models directory

Issue: Low response speed
Solution: Try smaller models or reduce context size with --context-size=512

Conclusion

You’ve now learned how to:

✅ Set up LocalAI with Docker
✅ Download and use open-source AI models
✅ Create a TypeScript client for AI interactions
✅ Handle advanced scenarios like chat and fine-tuning

The full code is available on GitHub. Happy coding with AI! 🚀

原创 高质量