kani (卡尼)

kani (卡尼) 是一个轻量级且高度可扩展的框架，专为支持工具使用/函数调用的聊天型语言模型而设计。

与其他语言模型框架相比，kani 的立场更加中立，并提供了对关键控制流程部分更精细的自定义能力，因此无论是 NLP 研究人员、爱好者还是开发者，它都是理想的选择。

kani 开箱即用地支持以下模型，并提供了一个与模型无关的框架，以便轻松添加更多模型的支持：

• OpenAI 模型（pip install "kani[openai]"）
• Anthropic 模型（pip install "kani[anthropic]"）
• Google AI 模型（pip install "kani[google]"）
• Hugging Face 转换器（pip install "kani[huggingface]"）
• llama.cpp（pip install "kani[cpp]"）
• vLLM（pip install "kani[vllm]"）
• 以及更多通过社区扩展实现！

请查看模型库，了解在 kani 中加载流行模型的代码示例！

有兴趣贡献代码吗？请参阅我们的贡献指南。

在 ReadTheDocs 上阅读文档！

在 arXiv 上阅读我们的论文！

安装

kani 需要 Python 3.10 或更高版本。为了安装特定于模型的依赖项，kani 使用了不同的额外组件（在 pip install 命令中库名后的方括号内）。要确定需要安装哪些额外组件，请参阅kani 的模型表格，或者使用 [all] 组件一次性安装所有内容。

# 对于 OpenAI 模型
$ pip install "kani[openai]"
# 对于 Hugging Face 模型
$ pip install "kani[huggingface]" torch
# 对于多模态输入
$ pip install "kani[multimodal]"
# 或者安装所有内容：
$ pip install "kani[all]"

若需获取最新更改和新增模型，您也可以从 Git 的 main 分支安装开发版本：

$ pip install "kani[all] @ git+https://github.com/zhudotexe/kani.git@main"

快速入门

kani 需要 Python 3.10 或更高版本。

首先，安装该库。在本快速入门中，我们将使用 OpenAI 引擎，尽管 kani 是与模型无关的。

$ pip install "kani[openai]"

接下来，让我们使用 kani 创建一个简单的聊天机器人，后端采用 ChatGPT。

# 导入库
import asyncio
from kani import Kani, chat_in_terminal
from kani.engines.openai import OpenAIEngine

# 请在此处替换为您的 OpenAI API 密钥：https://platform.openai.com/account/api-keys
api_key = "sk-..."

# kani 使用引擎与语言模型进行交互。您可以在此处指定其他模型参数，例如 temperature=0.7。
engine = OpenAIEngine(api_key, model="gpt-5-nano")

# kani 负责管理聊天状态、提示和函数调用。在这里，我们仅为其提供调用 ChatGPT 的引擎，但您也可以在此处指定其他参数，如 system_prompt="你是一个..."。
ai = Kani(engine)

# kani 提供了一个实用程序，可通过终端与 kani 交互...
chat_in_terminal(ai)


# 或者您也可以在异步函数中以编程方式使用 kani！
async def main():
    resp = await ai.chat_round("一只未载重的燕子的飞行速度是多少？")
    print(resp.text)


asyncio.run(main())

kani 缩短了搭建可用聊天模型所需的时间，同时为程序员提供了对每个提示、函数调用，甚至底层语言模型的深度自定义能力。

函数调用

函数调用使语言模型能够根据其文档，自主决定何时调用您提供的函数。

[!注意] 想要支持 MCP 吗？kani 也支持本地和远程 MCP 服务器。请参阅 MCP 文档：https://kani.readthedocs.io/en/latest/function_calling.html#mcp-tools。

借助 kani，您只需使用一行代码——@ai_function 装饰器——即可用 Python 编写函数并将其暴露给模型。

# 导入库
import asyncio
from typing import Annotated
from kani import AIParam、Kani、ai_function、chat_in_terminal、ChatRole
from kani.engines.openai import OpenAIEngine

# 按照上述方法设置引擎
api_key = "sk-..."
engine = OpenAIEngine(api_key, model="gpt-4o-mini")


# 继承 Kani 类以添加 AI 函数
class MyKani(Kani):
    # 将注解添加到方法即可将其暴露给 AI
    @ai_function()
    def get_weather(
        self,
        # 您还可以为特定参数提供额外的说明
        location: Annotated[str, AIParam(desc="城市和州，例如旧金山，加州")],
    ):
        """获取指定地点的当前天气状况"""
        # 在此示例中，我们模拟返回值，但您也可以调用真实的天气 API
        return f"{location} 的天气：晴朗，华氏 72 度。"


ai = MyKani(engine)

# 终端实用程序允许您测试函数调用...
chat_in_terminal(ai)


# 您也可以以编程方式跟踪多个回合。
async def main():
    async for msg in ai.full_round("东京的天气如何？"):
        print(msg.role, msg.text)


asyncio.run(main())

kani 确保函数调用在到达您的方法之前始终有效，同时让您专注于编写代码。如需更多信息，请参阅函数调用文档。

流式传输

kani 支持从底层语言模型逐 token 流式响应，即使在存在函数调用的情况下也是如此。流式传输被设计为 chat_round 和 full_round 方法的直接替代和扩展，使您能够逐步重构代码，而不会使其处于不完整状态。

async def stream_chat():
    stream = ai.chat_round_stream("Kani 是什么意思？")
    async for token in stream:
        print(token, end="")
    print()
    msg = await stream.message()  # 或者 `await stream`


async def stream_with_function_calling():
    async for stream in ai.full_round_stream("东京的天气如何？"):
        async for token in stream:
            print(token, end="")
        print()
        msg = await stream.message()

多模态输入

kani 可选地支持多种语言模型的多模态输入（图像、音频、视频）。要使用多模态输入，请安装 kani-multimodal-core 扩展包，或使用 pip install "kani[multimodal]"。更多信息请参阅 kani-multimodal-core 的文档。

阅读 kani-multimodal-core 文档！

from kani import Kani
from kani.engines.openai import OpenAIEngine
from kani.ext.multimodal_core import ImagePart

engine = OpenAIEngine(model="gpt-4.1-nano")
ai = Kani(engine)

# 注意参数是一个部件列表，而不是单个字符串！
msg = await ai.chat_round_str([
    "请描述这些图片：",
    ImagePart.from_file("path/to/image.png"),
    await ImagePart.from_url(
        "https://upload.wikimedia.org/wikipedia/commons/thumb/5/53/Whitehead%27s_Trogon_0A2A6014.jpg/1024px-Whitehead%27s_Trogon_0A2A6014.jpg"
    ),
])
print(msg)

多模态处理与 kani 生态系统的其他部分深度集成，因此您可以以最小的开发成本获得 kani 流畅工具使用和自动上下文管理的所有优势！

kani CLI

kani 自带一个命令行界面，让您无需任何设置即可在终端中与模型对话。

kani CLI 的形式为 $ kani <provider>:<model-id>。使用 kani --help 获取更多信息。

示例：

$ kani openai:gpt-4.1-nano
$ kani huggingface:meta-llama/Meta-Llama-3-8B-Instruct
$ kani anthropic:claude-sonnet-4-0
$ kani google:gemini-2.5-flash

此 CLI 辅助工具会自动创建 Engine 和 Kani 实例，并调用 chat_in_terminal()，以便您更快地测试大语言模型。当安装了 kani-multimodal-core 时，您可以将磁盘上或互联网上的多模态媒体提供给模型，只需在路径或 URL 前面加上 @ 符号：

USER: 请描述这张图片：@path/to/image.png，还有这张：@https://example.com/image.png

为什么选择 kani？

• 轻量级且高级 - kani 实现了与语言模型交互的常见样板代码，而不会强制您使用带有特定观点的提示框架或复杂的库专用工具。
• 模型无关 - kani 提供了一个简单的接口来实现：token 计数和完成生成。kani 允许开发者在不进行大规模代码重构的情况下切换后端运行的语言模型。
• 自动聊天记忆管理 - 让聊天会话流畅进行，无需担心管理历史记录中的 token 数量——kani 会为您处理。
• 带有模型反馈和重试功能的函数调用 - 只需一行代码即可让模型访问函数。kani 巧妙地提供关于幻觉参数和错误的反馈，并允许模型重试调用。
• 您控制提示 - 没有隐藏的提示技巧。与其他流行的语言模型库不同，我们绝不会替您决定如何格式化自己的数据。
• 快速迭代且易于学习 - 使用 kani，您只需编写 Python 代码——剩下的交给我们处理。
• 从一开始就采用异步设计 - kani 可以轻松扩展到并行运行多个聊天会话，而无需管理多个进程或程序。

现有的语言模型框架，如 LangChain 和 simpleaichat，往往带有特定的观点或过于臃肿——它们会在后台修改开发者的提示，学习起来颇具挑战性，而且如果不向代码库中添加大量难以维护的冗余代码，就很难进行自定义。

我们构建 kani 是为了提供一种更灵活、简单且健壮的替代方案。如果用框架之间的类比来说明，可以说 kani 之于 LangChain 就如同 Flask（或 FastAPI）之于 Django。

kani 适合从学术研究人员到行业专业人士，再到业余爱好者等各类用户使用，无需担心底层的黑箱操作。

文档

要了解更多关于如何 使用您自己的提示包装器来自定义 kani、函数调用 等内容，请 阅读文档！

或者查看本仓库中的实践示例：https://github.com/zhudotexe/kani/tree/main/examples。

演示

想亲眼看看 kani 的实际效果吗？我们在 GitHub Actions 的测试套件中运行了一个小型语言模型：

https://github.com/zhudotexe/kani/actions/workflows/pytest.yml?query=branch%3Amain+is%3Asuccess

只需点击最新的构建，即可查看模型的输出！

我们是谁

核心开发团队由宾夕法尼亚大学计算机与信息科学系的三名博士生组成。我们都是Chris Callison-Burch教授实验室的成员，致力于推动自然语言处理领域的未来发展。

• Andrew Zhu 于2022年秋季加入。他的研究兴趣包括自然语言处理、编程语言、分布式系统等。他同时也是一名全栈软件工程师，精通后端、DevOps、数据库和前端开发等多个领域。Andrew 致力于编写符合语言习惯、简洁、高效且易于维护的代码——这些理念在学术界并不常见。他的研究得到了美国国家科学基金会研究生研究奖学金的支持。

• Liam Dugan 于2021年秋季加入。他的研究主要集中在大型语言模型及其与人类的交互上。特别是，他对人类识别生成文本的能力以及如何将这些洞察应用于自动检测系统非常感兴趣。此外，他还关注大型语言模型在教育领域的实际应用。

• Alyssa Hwang 于2020年秋季加入，由Chris Callison-Burch和Andrew Head共同指导。她的研究专注于能够有效传达复杂信息的人工智能助手，例如通过语音助手引导用户完成操作，或通过有声读物帮助用户流畅地浏览文本内容。除了科研工作外，Alyssa 还担任宾夕法尼亚大学计算机与信息科学系博士生协会主席，创立了该系的博士生导师计划，并获得了美国国家科学基金会研究生研究奖学金的支持。

我们在研究中积极使用Kani，并努力使其与现代自然语言处理实践保持同步。

引用

如果您使用Kani，请按以下方式引用我们：

@inproceedings{zhu-etal-2023-kani,
    title = "Kani: 用于构建语言模型应用的轻量级且高度可扩展的框架",
    author = "Zhu, Andrew  and
      Dugan, Liam  and
      Hwang, Alyssa  and
      Callison-Burch, Chris",
    editor = "Tan, Liling  and
      Milajevs, Dmitrijs  and
      Chauhan, Geeticka  and
      Gwinnup, Jeremy  and
      Rippeth, Elijah",
    booktitle = "第三届自然语言处理开源软件研讨会（NLP-OSS 2023）论文集",
    month = dec,
    year = "2023",
    address = "新加坡",
    publisher = "计算语言学协会",
    url = "https://aclanthology.org/2023.nlposs-1.8",
    doi = "10.18653/v1/2023.nlposs-1.8",
    pages = "65--77",
}

致谢

我们感谢Chris Callison-Burch教授实验室的各位成员，他们对我们的论文和Kani代码库的内容进行了测试并提供了详尽的反馈。此外，我们还要感谢Henry Zhu（与第一作者无亲属关系），他在项目早期给予了热情的支持。

本研究部分得到了美国空军研究实验室（合同编号FA8750-23-C-0507）、IARPA HIATUS计划（合同编号2022-22072200005）以及美国国家科学基金会（资助号1928631）的支持。经批准公开发布，可自由传播。文中所表达的观点和结论均属作者个人意见，不应被视为代表IARPA、NSF或美国政府的官方政策，无论明示或暗示。

Kani 快速上手指南

Kani (カニ) 是一个轻量级、高可定制化的基于聊天的语言模型框架，原生支持工具调用/函数调用 (Function Calling)。与 LangChain 等重型框架不同，Kani 不强制使用特定的提示词模板，让开发者完全掌控对话流程和 Prompt 设计，非常适合 NLP 研究人员和需要精细控制的开发者。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.10 或更高版本
• 前置依赖：无特殊系统级依赖，仅需标准的 Python 环境。

安装步骤

Kani 采用模块化安装方式，根据你需要使用的模型后端安装对应的扩展包。

1. 基础安装（推荐国内用户配置镜像源）

建议使用国内镜像源（如清华源）加速安装：

# 设置临时镜像源并安装核心库及 OpenAI 支持
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "kani[openai]"

2. 其他模型后端安装

根据你的需求选择对应的额外依赖：

# Hugging Face Transformers 支持 (需额外安装 torch)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "kani[huggingface]" torch

# Anthropic (Claude) 支持
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "kani[anthropic]"

# Google AI (Gemini) 支持
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "kani[google]"

# llama.cpp 支持
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "kani[cpp]"

# vLLM 支持
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "kani[vllm]"

# 安装所有支持的引擎（体积较大）
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "kani[all]"

提示：若想体验最新功能，可从 GitHub 安装开发版： pip install "kani[all] @ git+https://github.com/zhudotexe/kani.git@main"

基本使用

1. 最简单的聊天机器人

以下示例展示如何使用 OpenAI 模型创建一个简单的聊天机器人。

import asyncio
from kani import Kani, chat_in_terminal
from kani.engines.openai import OpenAIEngine

# 替换为你的 OpenAI API Key
api_key = "sk-..."

# 初始化引擎，可在此指定 model, temperature 等参数
engine = OpenAIEngine(api_key, model="gpt-4o-mini")

# 初始化 Kani 实例，管理对话状态和上下文
ai = Kani(engine)

# 方式一：直接在终端交互
chat_in_terminal(ai)

# 方式二：在代码中异步调用
async def main():
    resp = await ai.chat_round("What is the airspeed velocity of an unladen swallow?")
    print(resp.text)

asyncio.run(main())

2. 使用命令行工具 (CLI)

Kani 内置了 CLI 工具，无需编写代码即可在终端直接与模型对话。

# 格式：kani <provider>:<model-id>
kani openai:gpt-4o-mini
kani huggingface:meta-llama/Meta-Llama-3-8B-Instruct
kani anthropic:claude-sonnet-4-0

多模态支持：若安装了 kani[multimodal]，可在 CLI 中通过 @ 前缀发送图片：

USER: Please describe this image: @path/to/image.png

3. 实现函数调用 (Function Calling)

Kani 的核心优势在于极简的函数调用支持。只需使用 @ai_function 装饰器，即可让模型自动调用你的 Python 函数。

import asyncio
from typing import Annotated
from kani import AIParam, Kani, ai_function, ChatRole
from kani.engines.openai import OpenAIEngine

api_key = "sk-..."
engine = OpenAIEngine(api_key, model="gpt-4o-mini")

class MyKani(Kani):
    # 使用装饰器暴露函数给 AI
    @ai_function()
    def get_weather(
        self,
        # 为参数添加描述，帮助模型理解
        location: Annotated[str, AIParam(desc="The city and state, e.g. San Francisco, CA")],
    ):
        """Get the current weather in a given location."""
        # 此处模拟返回，实际可调用真实 API
        return f"Weather in {location}: Sunny, 72 degrees fahrenheit."

ai = MyKani(engine)

async def main():
    # full_round 会自动处理函数调用循环，直到模型给出最终回答
    async for msg in ai.full_round("What's the weather in Tokyo?"):
        print(msg.role, msg.text)

asyncio.run(main())

4. 流式输出 (Streaming)

Kani 原生支持流式响应，即使包含函数调用也能逐字输出。

async def stream_chat():
    # chat_round_stream 返回一个异步生成器
    stream = ai.chat_round_stream("What does kani mean?")
    async for token in stream:
        print(token, end="", flush=True)
    print()
    
    # 获取完整消息对象
    msg = await stream.message()

Kani 的设计理念是“轻量且可控”，它自动处理上下文记忆管理和函数调用的重试逻辑，让你专注于业务逻辑和 Prompt 优化。更多高级用法请参考官方文档。