# libcai

**Repository Path**: tinytaro/libcai

## Basic Information

- **Project Name**: libcai
- **Description**: 大模型在线推理C语言函数库
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2025-03-11
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# libcai - 大模型在线推理C语言函数库

## 项目概述

libcai是一个轻量级、高性能的C语言函数库，专门用于调用大模型的在线推理API。它为开发者提供了简洁而强大的接口，使您能够轻松地将大模型AI推理能力集成到自己的应用程序中，无论是桌面应用、嵌入式系统还是服务器端应用。

## 主要特性

- **多模型兼容**: 支持包括DeepSeek、通义千问、ChatGPT等多种主流大模型API
- **多模态支持**: 不仅支持文本，还支持图像、音频和视频等多模态输入
- **高性能实现**: 纯C语言编写，内存占用低，性能卓越
- **健壮的错误处理**: 提供全面的错误检查和异常处理
- **流式响应**: 支持大模型的流式输出，实现实时交互体验
- **跨平台兼容**: 支持Linux、Windows、macOS等多种操作系统
- **外部依赖少**: 仅依赖于libcurl和jansson库，无其他第三方依赖

## 安装指南

### 前置依赖

本项目依赖于libcurl和jansson库，您需要先安装这些开发包：

```bash
# Debian/Ubuntu系统
sudo apt install -y libcurl4-openssl-dev libjansson-dev

# CentOS/RHEL系统
sudo yum install -y libcurl-devel jansson-devel

# macOS系统
brew install curl jansson
```

### 编译安装

```bash
# 克隆仓库
git clone https://gitee.com/tinytaro/libcai.git
cd libcai

# 初始化并更新子模块
git submodule update --init --recursive

# 创建构建目录并编译
mkdir build && cd build
cmake ..
make

# 安装库和头文件（可选）
sudo make install
```

## 快速入门

### 命令行工具使用

libcai提供了一个命令行工具，您可以直接使用它与大模型进行交互：

```bash
# 基本用法：向AI提问
./main "你好，你是谁？"

# 多模态输入：发送问题和图像
./main "这张图片里有什么？" "path/to/image.jpg"
```

### 编程示例

以下是一个简单的示例，展示如何使用libcai与大模型进行对话：

```c
#include <stdio.h>
#include <stdlib.h>
#include "cai.h"

int main(int argc, char* argv[]) {
    if (argc < 2) {
        fprintf(stderr, "Usage: %s <question> <file>\n", argv[0]);
        return EXIT_FAILURE;
    }

    // 创建AI助手实例
    struct cai_asst* asst = cai_asst_create("YOUR_API_KEY", 
                                            "https://api.example.com/v1", 
                                            "model-name");
    if (!asst) {
        fprintf(stderr, "创建客户端失败\n");
        return EXIT_FAILURE;
    }

    // 从文件中加载历史对话
    struct cai_convo* convo = cai_convo_load("history.json");
    if (!convo) {
        // 如果加载失败，创建新对话
        convo = cai_convo_create("你是一个智能摄像头", 0);
    }

    // 发送用户输入到AI助手并打印回复
    puts(cai_asst_chat(asst, convo, argv[1], argv[2]));

    // 持久化保存对话上下文
    cai_convo_save(convo, "history.json");
    
    // 销毁对话实例
    cai_convo_destroy(convo);
    // 销毁AI助手实例
    cai_asst_destroy(asst);

    return EXIT_SUCCESS;
}
```

编译
```bash
$ ls
main.c cai.h libcai.a

$ cc main.c -L. -lcai -lcurl
```

更多详细示例请参考`main.c`文件。

## 多模态支持

libcai支持处理多种类型的输入：

```c
// 发送图像并询问内容
answer = cai_asst_chat(asst, convo, "这张图片里有什么？", "path/to/image.jpg");

// 发送视频并请求分析
answer = cai_asst_chat(asst, convo, "视频中展示了什么内容？", "path/to/video.mp4");
```

## API文档

详细API文档如下，基于头文件`lib/cai.h`：

### 对话管理函数

- **`struct cai_convo* cai_convo_create(const char* prompt, int max)`**
  - 创建新的对话上下文
  - 参数：
    - `prompt`：系统提示词，NULL为不使用
    - `max`：对话保存的最多消息数，0为不限制（已弃用）
  - 返回：成功返回对话结构体地址，失败返回NULL

- **`void cai_convo_destroy(struct cai_convo* convo)`**
  - 销毁对话上下文
  - 参数：
    - `convo`：对话结构体地址

- **`struct cai_convo* cai_convo_load(const char* file)`**
  - 从文件中加载对话上下文
  - 参数：
    - `file`：保存对话上下文的文件路径
  - 返回：成功返回对话结构体地址，失败返回NULL

- **`int cai_convo_save(struct cai_convo* convo, const char* file)`**
  - 将对话上下文保存到文件中
  - 参数：
    - `convo`：对话结构体地址
    - `file`：保存对话上下文的文件路径
  - 返回：成功返回0，失败返回-1

### AI助手函数

- **`struct cai_asst* cai_asst_create(const char* api_key, const char* base_url, const char* model)`**
  - 创建AI助手实例
  - 参数：
    - `api_key`：API认证密钥
    - `base_url`：API服务地址
    - `model`：模型名称
  - 返回：成功返回AI助手结构体地址，失败返回NULL

- **`void cai_asst_set_temperature(struct cai_asst* asst, float temperature)`**
  - 设置温度参数
  - 参数：
    - `asst`：AI助手结构体地址
    - `temperature`：温度参数

- **`void cai_asst_set_format(struct cai_asst* asst, const char* format)`**
  - 设置输出格式
  - 参数：
    - `asst`：AI助手结构体地址
    - `format`：输出格式，如"json_object"、"text"等

- **`void cai_asst_destroy(struct cai_asst* asst)`**
  - 销毁AI助手实例
  - 参数：
    - `asst`：AI助手结构体地址

- **`void cai_set_stream_callback(struct cai_asst* asst, cai_stream_callback callback, void* userdata)`**
  - 设置流式响应回调函数
  - 参数：
    - `asst`：AI助手结构体地址
    - `callback`：回调函数
    - `userdata`：用户自定义数据指针

- **`char* cai_asst_chat(struct cai_asst* asst, struct cai_convo* conv, const char* question, const char* file)`**
  - 与AI助手对话
  - 参数：
    - `asst`：AI助手结构体地址
    - `conv`：对话结构体地址，如果为NULL，则不保存对话上下文
    - `question`：用户的问题
    - `file`：输入的文件，用于支持多模态的大模型，可以为NULL
  - 返回：返回AI助手的回答，会自动释放

## 故障排除

常见问题及解决方法：

- **编译错误**: 确保已安装正确版本的libcurl开发包
- **连接失败**: 检查API密钥和基础URL是否正确
- **内存问题**: 确保正确释放所有通过API获取的资源

## 贡献指南

我们欢迎社区贡献！如果您想参与项目开发：

1. Fork本仓库
2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的改动 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开一个Pull Request

## 社区和支持

- **代码仓库**: [https://gitee.com/tinytaro/libcai](https://gitee.com/tinytaro/libcai)
- **问题反馈**: 请通过Gitee Issues提交问题或建议
- **联系方式**: 可通过项目Issues页面联系维护者

## 许可证

本项目使用Apache License 2.0许可证，详情请参阅[LICENSE](LICENSE)文件。