快速入门

环境配置要求

• Go 版本：推荐使用 Go 1.18 及以上版本。如果需要使用最新的 pipeline 泛型工作流特性，请确保您的环境安装了 Go 1.24+。
• 网络环境：如果使用海外模型（如 OpenAI、Anthropic），请确保您的网络环境能够顺利访问相关 API 端点。

安装步骤

在您的 Go 项目根目录下，运行以下命令获取 GoChat：

go get github.com/DotNetAge/gochat

如有必要，清理并验证依赖项：

go mod tidy
go mod verify

基础使用示例

以下提供一个可直接运行的基础示例。该示例展示了如何使用 OpenAI 兼容客户端进行一次基础对话。

1. 基础对话 (Basic Chat)

创建一个 main.go 文件，并填入以下代码。运行前请确保已设置相关的环境变量（例如 DASHSCOPE_API_KEY 或您所用厂商的 API Key）：

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/DotNetAge/gochat/pkg/client/base"
    "github.com/DotNetAge/gochat/pkg/client/openai"
    "github.com/DotNetAge/gochat/pkg/core"
)

func main() {
    // 1. 获取您的 API Key
    apiKey := os.Getenv("DASHSCOPE_API_KEY")
    if apiKey == "" {
        log.Fatal("请先设置 DASHSCOPE_API_KEY 环境变量")
    }

    // 2. 初始化配置并创建客户端
    config := openai.Config{
        Config: base.Config{
            APIKey: apiKey,
            Model:  "qwen-plus", // 替换为您想使用的具体模型
            // BaseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1", // 默认已内置，也可自定义
        },
    }

    client, err := openai.New(config)
    if err != nil {
        log.Fatalf("创建客户端失败: %v", err)
    }

    // 3. 构建消息体
    messages := []core.Message{
        core.NewSystemMessage("你是一个专业的 Go 语言高级开发工程师。"),
        core.NewUserMessage("请解释一下 Go 语言中 Context 的核心作用。"),
    }

    // 4. 发起请求并使用 Functional Options 模式配置额外参数
    ctx := context.Background()
    resp, err := client.Chat(ctx, messages, 
        core.WithTemperature(0.7),
        core.WithMaxTokens(1000),
    )

    if err != nil {
        log.Fatalf("对话请求失败: %v", err)
    }

    // 5. 打印结果和 Token 消耗
    fmt.Println("=== AI 回复 ===")
    fmt.Println(resp.Content)
    fmt.Println("\n=== Token 统计 ===")
    fmt.Printf("总计消耗: %d Tokens\n", resp.Usage.TotalTokens)
}

2. 流式输出对话 (Streaming Chat)

对于长文本生成，流式输出能显著提升用户体验：

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/DotNetAge/gochat/pkg/client/base"
    "github.com/DotNetAge/gochat/pkg/client/openai"
    "github.com/DotNetAge/gochat/pkg/core"
)

func main() {
    client, _ := openai.New(openai.Config{
        Config: base.Config{
            APIKey: os.Getenv("API_KEY"),
            Model:  "qwen-plus",
        },
    })

    messages := []core.Message{
        core.NewUserMessage("给我写一首关于秋天的现代诗。"),
    }

    stream, err := client.ChatStream(context.Background(), messages)
    if err != nil {
        log.Fatalf("创建流失败: %v", err)
    }
    defer stream.Close()

    fmt.Print("AI: ")
    // 迭代流事件
    for stream.Next() {
        event := stream.Event()

        if event.Err != nil {
            log.Printf("\n流异常: %v\n", event.Err)
            break
        }

        // 根据事件类型处理
        switch event.Type {
        case core.EventThinking:
            // 处理推理模型的思考过程
            fmt.Printf("\033[90m%s\033[0m", event.Content) // 灰色打印思考内容
        case core.EventContent:
            // 处理标准内容输出
            fmt.Print(event.Content)
        }
    }
    fmt.Println()
}

运行以上代码，即可成功接入并体验 GoChat 的核心功能。如需了解更多模块（如 Embedding、Pipeline 等），请参阅模块文档。