Kosong:Moonshot AI开源的LLM抽象层,轻松构建多供应商兼容AI代理
一、Kosong是什么?
Kosong是由Moonshot AI开发的开源LLM(大语言模型)抽象层,名称源自马来语和印尼语中的“空”,寓意为AI代理开发提供灵活、无束缚的底层支撑。该项目基于Python 3.13+构建,核心目标是统一不同LLM的消息结构、标准化异步工具编排逻辑,并支持可插拔的聊天提供商集成,帮助开发者摆脱单一供应商锁定,高效构建功能完善的AI代理应用。
从本质上来说,Kosong并非一款独立的大语言模型,而是连接LLM、工具与应用的“中间件”。在AI代理开发过程中,开发者常常面临两大痛点:一是不同LLM供应商(如Kimi、Anthropic)的接口格式、消息结构差异较大,切换模型时需要大量修改代码;二是AI代理与外部工具(如API、本地脚本、数据处理模块)的交互逻辑复杂,异步编排难度高。Kosong通过标准化消息格式、封装工具调用流程、支持多供应商插件化集成,从根源上解决了这些问题,让开发者能够聚焦于业务逻辑,而非底层适配工作。
该项目采用Apache License 2.0开源许可证,允许开发者自由使用、修改和分发代码,无论是个人项目、商业应用还是企业级系统,都可基于Kosong进行二次开发,且无需支付任何授权费用。其核心定位是“AI代理开发的基础设施”,适用于从快速原型验证到生产环境部署的全流程场景。
二、功能特色
Kosong围绕“统一、灵活、高效”三大核心目标,构建了一系列贴合AI代理开发需求的功能模块,其特色可概括为以下七大核心亮点:
2.1 统一消息结构,打破LLM接口壁垒
不同LLM供应商的消息格式(如用户指令、系统提示、工具响应等)往往存在差异,导致开发者切换模型时需要大幅修改代码。Kosong通过message.py模块定义了标准化的消息结构,所有LLM交互都基于统一的Message类进行封装,包含role(角色,如user、assistant)、content(内容)等核心字段。
这种设计让开发者无需关注不同LLM的接口细节,只需按照Kosong的标准格式构建消息历史,即可无缝切换Kimi、Anthropic等不同供应商的模型。例如,在切换从Kimi到Anthropic模型时,无需修改消息组装逻辑,仅需更换chat_provider实例即可,极大降低了多模型兼容的开发成本。
2.2 可插拔聊天提供商,规避供应商锁定
Kosong的核心优势之一是支持“插件化”的聊天提供商集成。项目已内置Kimi(moonshotAI)、Anthropic等主流LLM的适配模块(位于chat_provider/目录),开发者可通过简单配置直接调用这些模型的能力。
同时,Kosong提供了标准化的ChatProvider接口,开发者只需按照接口规范实现自定义适配模块,即可轻松集成其他LLM供应商(如OpenAI、Google Gemini等)。这种设计从根本上避免了开发者被单一供应商锁定——当需要更换模型时,无需重构整个应用,仅需替换对应的聊天提供商插件,保障了项目的长期可扩展性。
2.3 强大的工具调用能力,支持复杂业务场景
AI代理的核心价值在于结合外部工具完成复杂任务(如数据计算、API调用、文件处理等)。Kosong提供了完善的工具调用框架,支持同步/异步工具调用、多工具组合使用、工具参数校验等功能。
其工具调用体系的核心组件包括:
SimpleToolset:轻量级工具集容器,支持通过+=运算符快速添加工具;CallableTool2:工具基类,开发者只需继承该类并实现__call__方法,即可定义自定义工具;ToolParams:基于Pydantic的参数校验机制,确保工具调用时的参数合法性;StepResult:工具调用结果封装,包含模型响应、工具执行结果等信息。
例如,开发者可快速定义“加法计算工具”“文件读取工具”等,AI代理会根据用户指令自动选择并调用对应的工具,无需手动编写调用逻辑。
2.4 流式输出支持,优化实时交互体验
对于智能客服、实时对话机器人等场景,流式输出(逐字/逐句返回模型响应)是提升用户体验的关键。Kosong内置了流式输出功能,通过StreamedMessagePart类封装流式响应片段,并提供on_message_part回调函数,允许开发者实时处理和展示模型输出。
流式输出不仅能减少用户等待时间,还能让开发者在响应过程中插入自定义逻辑(如内容过滤、格式转换等),适用于需要实时交互的各类AI代理应用。
2.5 灵活的消息存储,支持会话持久化
Kosong提供了内置的消息存储组件(位于contrib/linear.py),支持将对话历史以JSONL(JSON Lines)格式持久化存储。开发者可通过JsonlLinearStorage类快速实现会话记录的保存、读取和管理,无需自行设计存储方案。
这一功能对于需要追溯对话历史、分析用户行为、优化模型响应的场景尤为重要,例如智能客服系统的会话审计、教育类AI代理的学习轨迹记录等。
2.6 思考过程配置,精准控制模型响应细节
Kosong支持通过with_thinking方法配置模型的“思考努力程度”(低/中/高),不同等级对应模型生成响应时的思考深度和详细度。例如,在需要简洁答案的场景(如快速查询)可选择“低”等级,在需要复杂推理的场景(如数学解题、逻辑分析)可选择“高”等级。
这种灵活的配置机制让开发者能够根据具体业务需求,精准控制模型的响应质量和生成速度,实现体验与效率的平衡。
2.7 内置演示代理,快速体验核心功能
为了降低开发者的上手门槛,Kosong提供了内置的演示代理,支持本地快速运行。演示代理集成了bash工具调用功能,开发者只需配置Kimi API密钥,即可启动一个具备对话和命令执行能力的AI代理,直观体验Kosong的核心功能(如工具调用、流式输出等)。
三、技术细节
3.1 技术栈选型
Kosong的技术栈围绕Python生态构建,核心依赖与技术选型如下:
编程语言:Python 3.13+(要求较高版本Python以支持最新的异步特性和类型提示);
包管理器:推荐使用uv(一款快速、高效的Python包管理器,支持虚拟环境管理和依赖解析);
核心依赖:
pydantic:用于工具参数校验和数据模型定义,确保输入输出的合法性;
asyncio:Python内置异步IO框架,支撑Kosong的异步工具编排和流式输出功能;
typing-extensions:增强Python的类型提示能力,提升代码可读性和可维护性;
开发工具:
ruff:用于代码格式化和静态检查,确保代码风格一致性;
pyright:静态类型检查工具,提前发现类型相关错误;
pytest:单元测试框架,保障代码质量;
pdoc:自动生成API文档,方便开发者查阅。
3.2 核心架构与模块划分
Kosong的代码结构清晰,采用模块化设计,核心代码位于src/kosong/目录下,各模块职责明确,便于扩展和维护。以下是核心模块的功能说明:
| 模块路径 | 核心职责 | 关键组件/类 |
|---|---|---|
chat_provider/ | 集成不同LLM供应商,提供统一的调用接口 | Kimi、Anthropic、ChatProvider |
tooling/ | 工具调用相关逻辑封装,包括工具集、工具基类、参数校验等 | SimpleToolset、CallableTool2、ToolParams |
message.py | 定义标准化消息结构,支持消息的创建、校验和序列化 | Message、StreamedMessagePart |
contrib/ | 扩展功能模块,包括消息存储、额外工具等 | JsonlLinearStorage |
__init__.py |
核心API暴露,包括generate(生成响应)、step(工具调用步骤)等函数 | generate、step、StepResult |
除核心模块外,项目还包含tests/目录(单元测试)、pyproject.toml(项目配置)、Makefile(开发命令)、GitHub Actions工作流(CI/CD、自动发布)等辅助组件,形成了完整的开发和部署体系。
3.3 关键设计理念
3.3.1 解耦设计
Kosong的核心设计理念是“解耦”,通过分层架构实现不同模块的独立演进:
LLM层与业务层解耦:业务逻辑不直接依赖具体LLM,而是通过
ChatProvider接口交互;工具层与模型层解耦:工具的定义和调用不绑定特定模型,任何支持工具调用的LLM都可直接使用;
存储层与核心层解耦:消息存储功能作为扩展模块,开发者可根据需求选择使用或替换为自定义存储方案。
这种解耦设计确保了项目的灵活性和可扩展性,让开发者能够根据业务需求自由组合模块。
3.3.2 标准化与可扩展性
Kosong通过定义统一的接口和数据格式,实现了“一次开发,多端兼容”:
标准化接口:
ChatProvider(LLM集成)、CallableTool2(工具定义)等核心接口均有明确规范,便于第三方扩展;标准化数据格式:
Message类统一消息结构,StepResult统一工具调用结果格式,避免数据格式混乱;可扩展架构:核心模块预留扩展点,例如
chat_provider/目录支持新增LLM适配,tooling/目录支持自定义工具类型。
3.3.3 异步优先
考虑到AI代理开发中频繁的网络请求(如LLM调用、API请求)和工具调用场景,Kosong采用“异步优先”的设计思路,核心函数(如generate、step)均为异步函数(async/await),基于asyncio实现高效的并发处理。
异步设计能够有效提升应用的吞吐量和响应速度,避免因同步等待导致的性能瓶颈,尤其适用于需要同时处理多个用户请求或多个工具调用的场景。
3.4 代码质量保障
Kosong重视代码质量,建立了完善的质量保障体系:
静态检查:通过ruff和pyright对代码进行风格检查和类型校验,确保代码规范和类型安全;
单元测试:
tests/目录包含对聊天提供商、工具调用、消息处理等核心功能的单元测试,覆盖关键场景;自动化流程:GitHub Actions工作流实现了自动化测试、文档生成(pdoc)、PyPI发布和GitHub Pages部署,确保每次提交都经过严格验证;
版本管理:遵循语义化版本(SemVer)规范,版本更新透明,兼容性有保障。
四、应用场景
Kosong的核心优势在于“统一化”和“灵活性”,其应用场景覆盖了AI代理开发的多个领域,尤其适用于需要多LLM兼容、复杂工具调用或快速迭代的场景:
4.1 智能客服与对话机器人
在智能客服场景中,企业可能需要根据不同地区、不同业务场景切换LLM(如国内使用Kimi,海外使用Anthropic),同时需要集成知识库查询、订单查询、工单创建等工具。Kosong的统一消息结构和可插拔聊天提供商特性,让开发者无需为不同地区单独开发系统,只需通过配置切换LLM;而完善的工具调用框架则能让客服机器人自动调用各类业务工具,高效响应用户需求。
例如,用户咨询“我的订单物流状态”时,客服机器人可通过Kosong调用订单查询工具,获取物流信息后,再通过LLM生成自然语言回复,整个过程无需人工干预。
4.2 自动化办公助手
自动化办公助手需要处理文档解析、数据计算、邮件发送、日程管理等多种任务,涉及大量外部工具的集成。Kosong的工具调用能力和异步编排功能,能够让办公助手同时处理多个任务(如一边解析Excel数据,一边生成报告),并通过标准化的消息流程整合工具输出。
例如,开发者可基于Kosong构建“财务报表自动化助手”,集成Excel解析工具、数据计算工具、PDF生成工具,用户只需上传原始数据,助手即可自动完成数据处理、报表生成和邮件发送,大幅提升办公效率。
4.3 开发者快速原型开发
对于AI创业团队或独立开发者来说,快速验证产品想法是关键。Kosong提供了简洁的API和丰富的示例代码,开发者可在几小时内搭建起具备多LLM兼容、工具调用能力的AI代理原型,无需关注底层适配细节。
例如,开发者想要验证“AI数学导师”的产品想法,可通过Kosong快速集成Kimi模型和数学计算工具,实现“用户提问→模型分析→工具计算→结果反馈”的完整流程,快速收集用户反馈并迭代产品。
4.4 教育领域AI代理
教育类AI代理(如作业辅导机器人、语言学习助手)需要具备精准的逻辑推理、工具调用(如公式计算、单词查询)和个性化响应能力。Kosong的思考过程配置功能可根据学生的学习阶段调整模型响应的详细度(如小学生使用“高”思考等级,提供详细解题步骤;中学生使用“中”等级,简洁给出思路),而工具调用能力则能确保计算类题目答案的准确性。
例如,学生询问“2+3×4等于多少”时,AI代理可通过Kosong调用数学计算工具,避免模型生成错误答案,同时根据配置输出解题步骤,帮助学生理解。
4.5 实时交互类AI应用
直播助手、实时问答系统等应用需要快速响应用户请求,流式输出功能是关键。Kosong的流式输出特性能够让模型响应逐字返回,减少用户等待时间,同时支持在响应过程中插入自定义逻辑(如敏感词过滤、格式美化)。
例如,直播助手可通过Kosong调用Kimi模型,实时回应观众提问,流式输出回复内容,同时调用弹幕管理工具,自动过滤不恰当言论,提升直播互动体验。
4.6 企业级多模态AI代理
大型企业往往需要构建支持文本、语音、图像等多模态交互的AI代理,且需要兼容内部自研LLM和外部商用LLM。Kosong的可扩展架构支持新增多模态消息类型(如语音转文字、图像解析结果),并通过统一接口整合不同模态的工具和模型,帮助企业构建一体化的多模态AI代理系统。
例如,企业内部的“智能运维助手”可通过Kosong集成语音识别工具、设备监控API、内部知识库,运维人员可通过语音提问,助手自动识别语音、调用监控工具获取设备状态、查询知识库给出解决方案,实现高效运维。

五、使用方法
Kosong的使用流程简洁明了,主要分为“环境准备→安装→快速上手→自定义扩展”四个步骤,以下是详细的使用指南:
5.1 环境准备
5.1.1 系统要求
操作系统:支持Windows、macOS、Linux(无特殊限制);
Python版本:3.13或更高(必须满足,否则可能导致依赖安装失败或功能异常);
网络环境:需要联网下载依赖包和调用LLM API(如Kimi、Anthropic)。
5.1.2 包管理器安装
Kosong推荐使用uv作为包管理器(比pip更快、更高效),安装方式如下:
Windows/macOS/Linux:
# 安装uv(若已安装可跳过) curl -LsSf https://astral.sh/uv/install.sh | sh
安装完成后,可通过
uv --version验证是否安装成功。
5.2 安装Kosong
5.2.1 初始化项目(可选)
若为新项目,可通过uv初始化虚拟环境和项目结构:
# 初始化项目,指定Python版本为3.13 uv init --python 3.13 # 进入项目目录 cd your-project-name
5.2.2 添加Kosong依赖
通过uv安装Kosong:
uv add kosong
安装完成后,Kosong及其依赖(如pydantic、typing-extensions)会自动添加到项目的依赖列表中。
5.3 快速上手示例
Kosong提供了三类核心场景的示例代码,开发者可直接复制使用,只需替换API密钥等配置信息:
5.3.1 示例1:简单聊天完成
功能:调用Kimi模型,实现基础的对话交互(无工具调用)。
import asyncio
import kosong
from kosong.chat_provider.kimi import Kimi
from kosong.message import Message
async def main() -> None:
# 配置Kimi聊天提供商(替换为你的API密钥)
kimi = Kimi(
base_url="https://api.moonshot.ai/v1",
api_key="your_kimi_api_key_here",
model="kimi-k2-turbo-preview",
)
# 构建对话历史(用户消息)
history = [
Message(role="user", content="Who are you?"),
]
# 生成模型响应
result = await kosong.generate(
chat_provider=kimi, # 指定使用Kimi模型
system_prompt="You are a helpful assistant.", # 系统提示
tools=[], # 无工具调用
history=history, # 对话历史
)
# 输出结果(模型响应内容和token使用情况)
print("模型响应:", result.message)
print("Token使用:", result.usage)
# 运行异步函数
asyncio.run(main())5.3.2 示例2:流式输出
功能:调用Kimi模型,实现流式响应(逐字返回结果),适用于实时交互场景。
import asyncio
import kosong
from kosong.chat_provider import StreamedMessagePart
from kosong.chat_provider.kimi import Kimi
from kosong.message import Message
async def main() -> None:
# 配置Kimi聊天提供商
kimi = Kimi(
base_url="https://api.moonshot.ai/v1",
api_key="your_kimi_api_key_here",
model="kimi-k2-turbo-preview",
)
# 对话历史
history = [
Message(role="user", content="Please introduce yourself in 3 sentences."),
]
# 定义流式输出回调函数(实时打印响应片段)
def output(message_part: StreamedMessagePart):
print(message_part.content, end="") # end="" 确保逐字拼接
# 生成流式响应
result = await kosong.generate(
chat_provider=kimi,
system_prompt="You are a concise assistant.",
tools=[],
history=history,
on_message_part=output, # 绑定流式回调函数
)
# 输出完整结果和token使用情况
print("\n\n完整响应:", result.message)
print("Token使用:", result.usage)
asyncio.run(main())5.3.3 示例3:工具调用(使用kosong.step)
功能:定义自定义工具(加法计算),让模型自动调用工具完成任务。
import asyncio
from pydantic import BaseModel
import kosong
from kosong import StepResult
from kosong.chat_provider.kimi import Kimi
from kosong.message import Message
from kosong.tooling import CallableTool2, ToolOk, ToolReturnType
from kosong.tooling.simple import SimpleToolset
# 定义工具参数模型(使用Pydantic校验参数类型)
class AddToolParams(BaseModel):
a: int # 第一个整数
b: int # 第二个整数
# 定义加法工具(继承CallableTool2)
class AddTool(CallableTool2[AddToolParams]):
name: str = "add" # 工具名称(模型用于识别工具)
description: str = "Add two integers." # 工具描述(模型用于判断是否调用)
params: type[AddToolParams] = AddToolParams # 关联参数模型
# 实现工具逻辑
async def __call__(self, params: AddToolParams) -> ToolReturnType:
return ToolOk(output=str(params.a + params.b)) # 返回计算结果
async def main() -> None:
# 配置Kimi聊天提供商
kimi = Kimi(
base_url="https://api.moonshot.ai/v1",
api_key="your_kimi_api_key_here",
model="kimi-k2-turbo-preview",
)
# 创建工具集并添加加法工具
toolset = SimpleToolset()
toolset += AddTool() # 快速添加工具
# 对话历史(用户要求使用add工具计算2+3)
history = [
Message(role="user", content="Please add 2 and 3 with the add tool."),
]
# 执行工具调用步骤
result: StepResult = await kosong.step(
chat_provider=kimi,
system_prompt="You are a precise math tutor.",
toolset=toolset, # 指定使用的工具集
history=history,
)
# 输出结果
print("模型响应:", result.message)
print("工具调用结果:", await result.tool_results()) # 获取工具执行结果
asyncio.run(main())5.3.4 示例4:运行内置演示代理
功能:启动Kosong内置的演示代理,体验对话和bash工具调用功能。
配置环境变量(替换为你的Kimi API密钥):
Windows(命令提示符):
set KIMI_BASE_URL=https://api.moonshot.ai/v1 set KIMI_API_KEY=your_kimi_api_key
macOS/Linux(终端):
export KIMI_BASE_URL="https://api.moonshot.ai/v1" export KIMI_API_KEY="your_kimi_api_key"
运行演示代理:
uv run python -m kosong kimi --with-bash
启动后,可在终端中与代理交互,例如输入“执行ls命令”(macOS/Linux)或“执行dir命令”(Windows),代理会调用bash工具执行命令并返回结果。
5.4 常见示例对比
为了帮助开发者快速选择合适的示例,以下是核心示例的对比表格:
| 示例类型 | 核心功能 | 适用场景 | 关键代码亮点 |
|---|---|---|---|
| 简单聊天完成 | 基础对话,无工具调用 | 智能问答、客服回复 | kosong.generate、Message类 |
| 流式输出 | 实时逐字返回模型响应 | 直播助手、实时对话 | on_message_part回调函数 |
| 工具调用 | 模型自动调用自定义工具 | 数据计算、API调用、文件处理 | SimpleToolset、CallableTool2基类 |
| 内置演示代理 | 快速体验对话+bash工具调用 | 功能验证、快速原型 |
环境变量配置、--with-bash参数 |
5.5 自定义扩展:新增LLM提供商
若需集成Kosong未内置的LLM提供商(如OpenAI),可按照以下步骤实现:
新建
chat_provider/openai.py文件,继承ChatProvider接口;实现
generate和stream_generate方法(分别对应普通生成和流式生成);在代码中导入并使用自定义的
OpenAI聊天提供商。
示例代码框架(openai.py):
from typing import Optional, List from kosong.chat_provider.base import ChatProvider, GenerateResult, StreamGenerateResult from kosong.message import Message class OpenAI(ChatProvider): def __init__(self, base_url: str, api_key: str, model: str): self.base_url = base_url self.api_key = api_key self.model = model async def generate( self, system_prompt: str, history: List[Message], tools: List, **kwargs ) -> GenerateResult: # 实现OpenAI API的调用逻辑,返回标准化的GenerateResult pass async def stream_generate( self, system_prompt: str, history: List[Message], tools: List, on_message_part, **kwargs ) -> StreamGenerateResult: # 实现OpenAI流式API的调用逻辑,通过on_message_part返回片段 pass
六、常见问题解答(FAQ)
6.1 Kosong支持哪些LLM提供商?
目前Kosong已内置支持Kimi(moonshotAI)、Anthropic等主流提供商。开发者可通过自定义ChatProvider接口,扩展支持OpenAI、Google Gemini、百度文心一言等其他LLM提供商,具体可参考“自定义扩展”部分的指南。
6.2 为什么要求Python 3.13+?
Kosong依赖Python 3.13+的异步特性(如改进的asyncio性能、新的类型提示语法)和部分第三方库(如pydantic)的最新功能。使用低于3.13的Python版本可能导致依赖安装失败、功能异常或性能问题,建议升级Python版本后使用。
6.3 如何调试工具调用功能?
调试工具调用时,可通过以下方式排查问题:
检查工具的
name和description是否清晰——模型需要通过这些信息判断是否调用工具;验证工具参数模型(如
AddToolParams)是否正确,确保参数类型和必填项符合要求;通过
print(await result.tool_results())打印工具调用结果,查看是否返回ToolOk;若模型未调用工具,可优化
system_prompt,明确要求模型使用指定工具完成任务。
6.4 Kosong支持同步调用吗?
Kosong的核心函数(generate、step)均为异步函数(async/await),不直接支持同步调用。若需在同步代码中使用,可通过asyncio.run()封装,例如:
# 同步代码中调用异步函数 def sync_main(): asyncio.run(main()) # main()为之前定义的异步函数
6.5 消息存储支持哪些格式?
目前Kosong内置的消息存储组件(JsonlLinearStorage)支持JSONL格式,该格式便于逐行读取和写入,适合会话历史的持久化。若需支持其他格式(如CSV、数据库),可自定义存储类,实现add_message、get_history等核心方法。
6.6 Kosong是否适合生产环境部署?
是的,Kosong具备生产环境部署的条件:
采用Apache License 2.0许可证,商业使用无限制;
代码经过单元测试和静态检查,质量有保障;
支持异步并发,性能满足高吞吐量场景;
可通过扩展存储、日志、监控等组件,适配生产环境需求。
建议部署前做好以下准备:
完善错误处理逻辑(如LLM API调用失败重试、工具调用超时处理);
配置日志系统,记录模型响应、工具调用、错误信息等;
对敏感信息(如API密钥)进行加密存储,避免硬编码。
6.7 如何提高Kosong的性能?
提高性能可从以下方面入手:
使用uv作为包管理器,加快依赖安装和项目启动速度;
对于高频工具调用,可缓存工具结果,避免重复执行;
合理配置LLM模型参数(如
temperature、max_tokens),平衡响应速度和质量;采用异步并发处理多个用户请求,充分利用系统资源。
七、相关链接
GitHub仓库:https://github.com/MoonshotAI/kosong
八、总结
Kosong作为moonshotAI推出的开源LLM抽象层,以“统一化、灵活性、高效性”为核心,为AI代理开发提供了一站式解决方案。其通过标准化消息结构打破了不同LLM提供商的接口壁垒,以可插拔设计规避了供应商锁定风险,凭借完善的工具调用框架和异步编排能力,支撑起复杂业务场景的实现。无论是开发者快速验证产品原型、企业构建生产级AI代理,还是教育、办公等领域的定制化应用,Kosong都能通过简洁的API、丰富的示例和高度的可扩展性,降低开发门槛、提升开发效率。依托Python 3.13+的技术栈和Apache License 2.0的开源许可,Kosong在商业和非商业场景中都具备广泛的适用性,是AI代理开发领域值得关注和使用的优秀工具集。
版权及免责申明:本文由@人工智能研究所原创发布。该文章观点仅代表作者本人,不代表本站立场。本站不承担任何相关法律责任。
如若转载,请注明出处:https://www.aipuzi.cn/ai-news/kosong.html

