Simplemind: 为人类而生的AI™

保持简单，回归人性。

Simplemind 是一款专为 Python 设计的 AI 库，旨在简化您与 AI API 的交互体验。秉承“为人类而生”的理念，它抽象掉了复杂的细节，为开发者提供了一种直观且人性化的接口来使用强大的 AI 功能。

核心特性

有了 Simplemind，接入 AI 就像进行一次友好的对话一样简单。

• 易用的 AI 工具：Simplemind 提供了对大多数主流 AI 服务的简洁接口。
• 以人为本的设计：该库优先考虑代码的可读性和易用性——无需成为专家即可开始尝试。
• 极简配置：快速上手，无需为繁琐的配置操心。

支持的 API

所有支持的提供商和模型所使用的 API 接口完全一致：

	llm_provider	默认 llm_model
Anthropic 的 Claude	"anthropic"	"claude-3-5-sonnet-20241022"
亚马逊 Bedrock	"amazon"	"anthropic.claude-3-5-sonnet-20241022-v2:0"
Deepseek	"deepseek"	"deepseek-chat"
谷歌 Gemini	"gemini"	"models/gemini-1.5-pro"
Groq 的 Groq	"groq"	"llama3-8b-8192"
Ollama	"ollama"	"llama3.2"
OpenAI 的 GPT	"openai"	"gpt-4o-mini"
xAI 的 Grok	"xai"	"grok-beta"

要指定特定的提供商或模型，您可以在调用 generate_text、generate_data 或 create_conversation 时使用 llm_provider 和 llm_model 参数。

如果您希望 Simplemind 支持更多提供商或模型，请提交一个 Pull Request！

快速入门

Simplemind 会处理复杂的 API 调用细节，让您专注于真正重要的事情——构建、实验和创造。

$ pip install 'simplemind[full]'

首先，通过在环境变量中设置您的 API 密钥来进行身份验证：

$ export OPENAI_API_KEY="sk-..."

这种做法可以确保您的 API 密钥不会暴露在代码库中，从而保护您的隐私。其他支持的环境变量包括：ANTHROPIC_API_KEY、XAI_API_KEY、DEEPSEEK_API_KEY、GROQ_API_KEY 和 GEMINI_API_KEY。

接下来，导入 Simplemind 并开始使用：

import simplemind as sm

使用示例

以下是一些使用 Simplemind 的示例。

请注意：此处展示的大多数调用都可以选择性地接受 llm_provider 和 llm_model 参数，这两个参数应以字符串形式提供。

文本补全

根据给定的提示生成 AI 模型的响应：

>>> sm.generate_text(prompt="生命的意义是什么？")
"生命的意义是一个深刻的哲学问题，几个世纪以来一直被各种文化、宗教和哲学家探讨。不同的人和信仰体系对此有不同的解读：\n\n1. **宗教视角**：许多宗教认为，生命的意义在于实现神圣的目的、侍奉上帝或达到某种来世境界。例如，基督教通常强调爱、信仰以及侍奉上帝和他人是生命意义的核心。\n\n2. **哲学观点**：哲学家们给出了多种答案。存在主义者如让-保罗·萨特认为，生命本身并没有固有的意义，个人必须自己去创造生活的意义。而亚里士多德则认为，通过过一种有德行的生活来实现幸福（即‘圆满’），才是有意义的人生。\n\n3. **科学与世俗的观点**：有些人从理解自然世界、推动人类知识进步，或者通过个人成就和幸福找到生命的意义。他们可能认为生命的意义来源于人与人之间的连接、留下的遗产，或是对知识和创造力的追求。\n\n4. **个人视角**：对许多人来说，生命的意义是非常个人化的，它与他们的关系、热情和目标息息相关。这些人通过自己的经历、与他人的联系以及对他人和世界的影响力来定义生命的意义。\n\n总之，生命的意义是一个主观的问题，每个人都会根据自己的信仰、经历和思考得出不同的答案。"

流式文本生成

>>> for chunk in sm.generate_text("写一首关于月亮的诗", stream=True):
...     print(chunk, end="", flush=True)

使用 Pydantic 构建结构化数据

如果大模型支持，你可以使用 Pydantic 模型来组织大模型的响应。

class Poem(BaseModel):
    title: str
    content: str

>>> sm.generate_data("写一首关于爱的诗", response_model=Poem)
title='永恒的拥抱' content='在寂静的夜晚,\n当繁星低语着明亮的秘密时,\n两颗心以温柔的韵律跳动,\n共舞于时光的沙漏之中。\n\n每一次凝视都点燃一簇火花,\n那火焰温暖了最寒冷的黑夜,\n在共享的欢笑与甜蜜的呢喃中,\n爱将世界绘成一幅杰作。\n\n无论风雨交加还是阳光明媚,\n它以千变万化的形式找到归宿,\n一个温柔的触碰，一声会心的叹息,\n在爱的怀抱里，我们学会飞翔。\n\n随着季节更迭，时光流转,\n在我们编织的梦想织锦中,\n爱的丝线永恒不朽，紧紧相连,\n那是两颗灵魂共鸣的永恒纽带。\n\n所以，让我们为这份光明而真挚的爱干杯,\n这是一份不断重申、不断更新的礼物,\n在每一次心跳、每一句祈祷中,\n都有一个故事悄然书写于空气中。'

更复杂的示例

class InstructionStep(BaseModel):
    step_number: int
    instruction: str

class RecipeIngredient(BaseModel):
    name: str
    quantity: float
    unit: str

class Recipe(BaseModel):
    name: str
    ingredients: list[RecipeIngredient]
    instructions: list[InstructionStep]

recipe = sm.generate_data(
    "写一份巧克力曲奇饼干的食谱",
    response_model=Recipe,
)

特别感谢 @jxnl 开发的 Instructor，正是它让这一切成为可能！

对话式 AI

SimpleMind 也支持轻松构建对话流程：

>>> conv = sm.create_conversation()

>>> # 向对话中添加一条消息
>>> conv.add_message("user", "你好呀，最近怎么样？")

>>> conv.send()
<Message role=assistant text="你好！我只是一个计算机程序，没有感情，不过我很乐意帮助你。今天有什么可以帮你的吗？">

要继续对话，只需再次调用 conv.send()，它会返回对话中的下一条消息：

>>> conv.add_message("user", "生命的意义是什么？")
>>> conv.send()
<Message role=assistant text="生命的意义是一个深刻的哲学问题，几个世纪以来一直被不同文化、宗教和哲学家所探讨。不同的人和信仰体系对此有不同的解读：\n\n1. **宗教视角：** 许多宗教认为，生命的意义在于实现神圣的使命、侍奉上帝或达到某种来世境界。例如，基督教常强调爱、信仰以及对上帝和他人的服务是生命意义的核心。\n\n2. **哲学观点：** 哲学家们给出了多种答案。存在主义者如让-保罗·萨特认为，生命本身并无固有意义，每个人必须自己创造人生的目的。而亚里士多德则认为，通过美德生活实现“幸福”才是有意义的人生。\n\n3. **科学与世俗观点：** 有些人从理解自然世界、推动人类知识进步或追求个人成就和幸福中找到生命的意义。他们可能把生命的意义看作是人与人之间的联结、留下的遗产，或是对知识和创造力的追求。\n\n4. **个人视角：** 对许多人来说，生命的意义是非常个人化的，与他们的关系、热情和目标密切相关。这些人通过自己的经历、与他人的联系以及对他人和世界的影响力来定义生命的意义。\n\n总之，生命的意义是一个主观的问题，每个人都会根据自己的信仰、经历和思考得出不同的答案。">

避免重复代码

你可以使用 Session 类为所有调用设置默认参数：

# 创建一个带有默认值的会话
gpt_4o_mini = sm.Session(llm_provider="openai", llm_model="gpt-4o-mini")

# 现在所有的调用都会使用这些默认值
response = gpt_4o_mini.generate_text("你好！")
conversation = gpt_4o_mini.create_conversation()

这样既保持了原始 API 的简洁性，又减少了重复代码。

会话对象还支持在每次调用时覆盖默认值：

response = gpt_4o_mini.generate_text("这里有一个复杂任务", llm_model="gpt-4")

基础记忆插件

借助 Python 的强大功能，你可以轻松创建自己的插件，为对话添加额外的功能：

class SimpleMemoryPlugin(sm.BasePlugin):
    def __init__(self):
        self.memories = [
            "地球已经被虚构地毁灭了。",
            "月亮是由奶酪做成的。",
        ]

    def yield_memories(self):
        return (m for m in self.memories)

    def pre_send_hook(self, conversation: sm.Conversation):
        for m in self.yield_memories():
            conversation.add_message(role="system", text=m)


conversation = sm.create_conversation()
conversation.add_plugin(SimpleMemoryPlugin())


conversation.add_message(
    role="user",
    text="请写一首关于月亮的诗",
)

>>> conversation.send()
在浩瀚无垠的星空之下，
有一块奶酪圆盘遥遥相望。
它并非由岩石或银辉构成，
而是散发着切达奶酪的光芒。

在这寂静的宇宙中独自游荡，
远离故土，孤独而迷茫。
不再反射太阳的光辉，
如今却因它的趣味而闻名遐迩。

昔日曾是地球的伴侣，
如今却孤零零地漂泊在黑暗里。
月球表面不再是坑坑洼洼，
取而代之的是高达、瑞士和卡门贝尔奶酪的骄傲。

曾经的宇航员试图探索月球表面，
却发现那里并不是什么神秘之地，
而是一个充满奶酪乐趣的天堂，
在夜色中散发出柔和的光芒。

在这个奶酪主宰的世界里，
月亮带来了欢笑与奇妙的景象。
它不再只是沉默的天体，
而是欢乐与惊喜的象征，近在咫尺。

因此，让我们为这块披着奶酪外衣的月亮干杯，
它是宇宙乐章中一抹俏皮的音符。
提醒着我们，在童话与趣闻之间，
宇宙永远充满无限可能。

简单却有效。

工具（函数调用）

工具（也称为函数）允许你在 AI 对话中调用任何 Python 函数。以下是一个示例：

def get_weather(
    location: Annotated[
        str, Field(description="城市和州，例如旧金山，加州")
    ],
    unit: Annotated[
        Literal["摄氏度", "华氏度"],
        Field(
            description="温度单位，可选‘摄氏度’或‘华氏度’"
        ),
    ] = "摄氏度",
):
    """
    获取指定地点的当前天气
    """
    return f"42 {unit}"

# 将您的函数添加为工具
conversation = sm.create_conversation()
conversation.add_message("user", "旧金山的天气如何？")
response = conversation.send(tools=[get_weather])

请注意，我们使用了 Python 的 Annotated 特性结合 Field 来为函数参数提供额外的上下文信息。这有助于 AI 理解每个参数的意图和约束条件，从而使工具调用更加准确可靠。 您也可以省略 Annotated，只传递 Field 参数。

def get_weather(
    location: str = Field(description="城市和州，例如旧金山，加州"),
    unit:Literal["摄氏度", "华氏度"]= Field(
        default="摄氏度",
        description="温度单位，可以是'摄氏度'或'华氏度'"
        ),
):
    """
    获取指定地点的当前天气
    """
    return f"42 {unit}"

函数可以使用类型提示和 Pydantic 模型进行定义，以实现验证功能。LLM 会智能地选择何时调用这些函数，并将结果整合到其回复中。

🪄 使用 LLM 自动定义工具（实验性）

Simplemind 提供了一个装饰器，可以自动将 Python 函数转换为带有 AI 生成元数据的工具。只需使用 @simplemind.tool 装饰器，LLM 就会分析您的函数并生成适当的描述和模式：

@simplemind.tool(llm_provider="anthropic")
def haversine(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
    r = 6371
    phi1 = math.radians(lat1)
    phi2 = math.radians(lat2)
    delta_phi = math.radians(lat2 - lat1)
    delta_lambda = math.radians(lon2 - lon1)

    a = (
        math.sin(delta_phi / 2) ** 2
        + math.cos(phi1) * math.cos(phi2) * math.sin(delta_lambda / 2) ** 2
    )
    c = 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))
    d = r * c
    return d

请注意，我们并未为该函数添加任何文档字符串或 Field。装饰器会使用指定的 LLM 提供者来生成工具模式，包括描述和参数详情：

{
    "name": "haversine",
    "description": "根据两点的经纬度坐标，计算地球上两点之间的大圆距离",
    "input_schema": {
        "type": "object",
        "properties": {
            "lat1": {
                "type": "number",
                "description": "第一点的纬度，以十进制度数表示",
            },
            "lon1": {
                "type": "number",
                "description": "第一点的经度，以十进制度数表示",
            },
            "lat2": {
                "type": "number",
                "description": "第二点的纬度，以十进制度数表示",
            },
            "lon2": {
                "type": "number",
                "description": "第二点的经度，以十进制度数表示",
            }
        },
        "required": ["lat1", "lon1", "lat2", "lon2"],
    },
}

经过装饰后的函数就可以像其他工具一样，通过对话 API 使用。

conversation = sm.create_conversation()
conversation.add_message("user", "伦敦离我有多远")
response = conversation.send(tools=[get_location, get_coords, haversine]) # 可以传递多个工具

更多内容请参阅 examples/distance_calculator.py。

日志记录

Simplemind 使用 Logfire 进行日志记录。要启用日志记录，请调用 sm.enable_logfire()。

更多示例

请查看 examples 目录中的可执行示例。

---

贡献

我们欢迎各种形式的贡献。如果您发现任何 bug 或有新的功能需求，欢迎随时提交 issue；同时，我们也欢迎您通过提交 pull request 来帮助 SimpleMind 不断完善。

开始贡献的步骤如下：

1. Fork 本仓库。
2. 创建新分支。
3. 进行修改。
4. 提交 pull request。

许可证

Simplemind 采用 Apache 2.0 许可证。

致谢

Simplemind 的灵感来源于“为人类而编写的代码”这一理念，旨在让所有人都能轻松地使用 AI 模型。特别感谢开源社区的贡献与启发。

Simplemind 快速上手指南

Simplemind 是一个专为人类设计的 Python AI 库，旨在简化与各类主流 AI API 的交互。它通过统一的接口抽象了底层复杂性，让开发者能够以直观、人性化的方式调用强大的 AI 能力。

环境准备

• 系统要求：支持 Windows、macOS 和 Linux。
• Python 版本：建议 Python 3.8 及以上版本。
• 前置依赖：
  • 已安装 pip 包管理工具。
  • 拥有至少一个支持的 AI 服务商 API Key（如 OpenAI, Anthropic, DeepSeek 等）。

安装步骤

使用 pip 安装完整功能的 Simplemind：

pip install 'simplemind[full]'

提示：国内用户若遇到下载速度慢的问题，可尝试使用清华或阿里镜像源加速安装：

pip install 'simplemind[full]' -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 配置 API Key

在使用前，请将您的 API Key 设置为环境变量，以避免将其硬编码在代码中。

Linux/macOS:

export OPENAI_API_KEY="sk-..."
# 其他支持的变量：ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, XAI_API_KEY

Windows (PowerShell):

$env:OPENAI_API_KEY="sk-..."

2. 文本生成 (Text Completion)

导入库并调用 generate_text 即可开始对话。默认使用配置的模型，也可指定提供商和模型。

import simplemind as sm

# 最简单的调用方式
response = sm.generate_text(prompt="生命的意义是什么？")
print(response)

流式输出示例：

for chunk in sm.generate_text("写一首关于月亮的诗", stream=True):
    print(chunk, end="", flush=True)

3. 结构化数据输出 (Structured Data)

结合 Pydantic 模型，让 AI 直接返回格式化的 JSON 数据对象。

from pydantic import BaseModel
import simplemind as sm

class Poem(BaseModel):
    title: str
    content: str

# 让 AI 按照定义的结构返回数据
poem = sm.generate_data("写一首关于爱的诗", response_model=Poem)
print(poem.title)
print(poem.content)

4. 多轮对话 (Conversational AI)

使用 create_conversation 创建会话对象，轻松管理上下文。

import simplemind as sm

# 创建会话
conv = sm.create_conversation()

# 添加用户消息
conv.add_message("user", "你好，最近怎么样？")

# 发送并获取回复
response = conv.send()
print(response.text)

# 继续对话
conv.add_message("user", "生命的意义是什么？")
response = conv.send()
print(response.text)

5. 高级用法：会话管理与插件

设置默认参数 (Session)： 避免每次调用都重复指定模型参数。

# 创建一个默认使用 gpt-4o-mini 的会话对象
gpt_session = sm.Session(llm_provider="openai", llm_model="gpt-4o-mini")

# 该会话下的所有调用默认使用上述配置
response = gpt_session.generate_text("Hello!")
conversation = gpt_session.create_conversation()

自定义记忆插件 (Memory Plugin)： 通过继承 BasePlugin 为对话注入系统级记忆或上下文。

class SimpleMemoryPlugin(sm.BasePlugin):
    def __init__(self):
        self.memories = ["地球已经被虚构地毁灭了。", "月亮是由奶酪做的。"]

    def yield_memories(self):
        return (m for m in self.memories)

    def pre_send_hook(self, conversation: sm.Conversation):
        for m in self.yield_memories():
            conversation.add_message(role="system", text=m)

# 使用插件
conversation = sm.create_conversation()
conversation.add_plugin(SimpleMemoryPlugin())
conversation.add_message(role="user", text="请写一首关于月亮的诗")
print(conversation.send().text)

支持的服务商

Simplemind 统一了以下主流模型的接口，只需更改 llm_provider 和 llm_model 参数即可切换：

服务商	llm_provider 值	默认模型
Anthropic (Claude)	"anthropic"	"claude-3-5-sonnet-20241022"
Amazon Bedrock	"amazon"	"anthropic.claude-3-5-sonnet-20241022-v2:0"
DeepSeek	"deepseek"	"deepseek-chat"
Google Gemini	"gemini"	"models/gemini-1.5-pro"
Groq	"groq"	"llama3-8b-8192"
Ollama (本地)	"ollama"	"llama3.2"
OpenAI (GPT)	"openai"	"gpt-4o-mini"
xAI (Grok)	"xai"	"grok-beta"

切换模型示例：

# 使用 DeepSeek 模型
sm.generate_text("你好", llm_provider="deepseek", llm_model="deepseek-chat")