openJiuwen：国产开源生产级AI Agent平台实战指南

0 阅读

什么是 openJiuwen？

很多开发者第一次听到“openJiuwen”（开源九问）时，容易把它误认为是一个新的大语言模型。其实完全不是。openJiuwen 本身不提供任何大模型权重，它是一个生产级的 AI Agent（智能体）开发与运行平台。

这个项目由华为实验室、华为云以及小艺终端团队联合开源，遵循 Apache 2.0 协议。如果把 LangChain 比作是一堆乐高积木块，那么 openJiuwen 更像是一套已经搭好骨架、带轮子、能直接上路跑的整车系统。它的核心目标很明确：解决大模型应用从“Demo 好玩”到“生产可用”之间的鸿沟。

在真实的企业业务中，我们往往需要智能体记住之前的对话状态、在任务中断后能继续执行、或者让多个智能体分工合作。openJiuwen 正是为了解决这些痛点而生。它兼容所有 OpenAI 格式的接口，这意味着你可以无缝接入 Qwen（通义千问）、DeepSeek（深度求索）、GLM（智谱）或者本地的 Ollama 模型。

核心架构与模块解析

openJiuwen 的设计思路非常务实，主要包含以下几个核心模块，每个模块都对应着开发中的具体难题。

1. agent-core：底层运行引擎

这是平台的 Python SDK 核心，通过 pip install openjiuwen 即可安装。它支持两种主要的 Agent 模式：

  • ReAct Agent：经典的“推理-行动”循环，适合需要调用工具的场景。
  • Workflow：工作流模式，适合固定流程的任务。

更重要的是，它在底层实现了异步流式输出和状态持久化。这意味着当你的 Agent 正在处理一个耗时较长的任务时，如果服务重启或网络中断，它可以从中断的地方继续运行，而不是从头再来。这对于生产环境至关重要。

2. JiuwenSwarm：蜂群智能体协同

这是 openJiuwen 最具特色的组件。在处理复杂任务时，单个 Agent 往往力不从心。JiuwenSwarm 允许你创建多个子 Agent，让它们像蜂群一样协作。例如，一个 Agent 负责搜集信息，另一个负责总结，还有一个负责审核。这种原生的多智能体协同框架，比在 LangGraph 中手动编写复杂的图逻辑要直观得多。

3. Agent-Studio：可视化低代码面板

对于不想写大量代码的产品经理或业务人员，Agent-Studio 提供了一个 Web 界面。你可以拖拽组件来编排 Agent 的工作流，实时调试提示词（Prompt），并查看运行日志。整个平台可以通过 Docker 一键部署，降低了使用门槛。

4. DeepSearch：深度研究智能体

这是一个专门针对研报生成、深度调研场景优化的 Agent。它具备联网检索能力，并能对引用的内容进行片段级溯源，确保生成的报告有据可依，减少大模型的“幻觉”问题。

5. Agent-Runtime：运维与可观测性

除了开发，运维也是重点。该模块提供了分布式部署支持，以及全链路的调试追踪功能。你可以清楚地看到每一个 Token 是如何消耗的，每一步决策是如何做出的，这对于排查线上问题非常有帮助。

openJiuwen 与 LangChain 的对比

很多开发者会问：既然有了 LangChain，为什么还要用 openJiuwen？我们可以从以下几个维度来看：

维度 openJiuwen LangChain
侧重点 生产级多 Agent 蜂群协作、状态管理、断点续跑 通用 LLM 应用组件库，灵活性高但需自行组装
可视化 自带 Agent-Studio，零代码 Web 界面 需自行搭建或使用 LangSmith 等第三方工具
多 Agent 原生支持 JiuwenSwarm，开箱即用 需依赖 LangGraph 手动编写复杂的图逻辑
部署体验 支持 Docker 容器化整套平台部署 偏向 SDK 库，服务端部署需自行实现
模型兼容 兼容所有 OpenAI 格式 API 兼容几乎所有主流大模型

简单来说，如果你只是做一个简单的聊天机器人或单次问答应用，LangChain 可能更轻量、更灵活。但如果你要构建一个嵌入业务系统、需要长期记忆、多角色协作且要求高稳定性的企业级应用，openJiuwen 提供的“开箱即用”特性会节省大量的基建时间。

快速上手：Hello-Agent 最小可运行示例

接下来，我们通过几个具体的代码示例，看看如何使用 openJiuwen。请确保你的环境中安装了 Python 3.11 至 3.13 版本。

首先，安装依赖包：

pip install openjiuwen

示例 1：最简单的单 Agent 对话

这个示例展示了如何配置本地 Ollama 模型，并创建一个简单的 ReAct Agent 进行对话。

from openjiuwen import LLMConfig
from openjiuwen.agent import ReActAgent

# 1. 配置本地 Ollama，使用 OpenAI 兼容接口
llm_config = LLMConfig(
    api_base="http://127.0.0.1:11434/v1",
    api_key="dummy",  # Ollama 默认不需要 key，填任意字符串即可
    model="qwen3-8b",  # 确保你本地已拉取该模型
    provider="openai_compatible"
)

# 2. 构建 ReAct 智能体
agent = ReActAgent(
    llm_config=llm_config,
    system_prompt="你是一个简洁助手，回答尽量简短。"
)

def main():
    query = "简单介绍多Agent架构"
    print(f"User: {query}")
    # 运行 Agent
    resp = agent.run(query)
    print(f"Agent: {resp.content}")

if __name__ == "__main__":
    main()

注意：在运行前，请确保 Ollama 服务已经启动（ollama serve），并且你已经拉取了 qwen3-8b 模型（ollama pull qwen3-8b）。

示例 2：JiuwenSwarm 蜂群多 Agent 协作

这个示例展示了如何让两个 Agent 分工合作：一个负责搜集要点，另一个负责总结成文。

from openjiuwen import LLMConfig
from openjiuwen.agent import ReActAgent
from openjiuwen.swarm import JiuwenSwarm

llm_config = LLMConfig(
    api_base="http://127.0.0.1:11434/v1",
    api_key="dummy",
    model="qwen3-8b",
    provider="openai_compatible"
)

# 子 Agent 1：信息搜集助手
search_agent = ReActAgent(
    llm_config=llm_config,
    name="信息搜集助手",
    system_prompt="负责梳理问题要点，列出关键信息点，只输出要点列表。"
)

# 子 Agent 2：总结写作助手
summary_agent = ReActAgent(
    llm_config=llm_config,
    name="总结写作助手",
    system_prompt="接收搜集到的要点，整理成通顺完整的中文段落。"
)

# 构建蜂群，编排协作
swarm = JiuwenSwarm(
    llm_config=llm_config,
    agents=[search_agent, summary_agent]
)

def main():
    question = "简单讲一下提示词工程 Few-Shot 与 ICL 区别"
    result = swarm.run(question)
    print("Swarm 输出：")
    print(result.content)

if __name__ == "__main__":
    main()

在这个例子中，JiuwenSwarm 会自动协调两个 Agent 的执行顺序和数据传递，你无需关心中间的通信细节。

示例 3：对接云端模型（如 DashScope）

如果你不想使用本地模型，也可以轻松切换到阿里云 DashScope 等云服务。只需修改 LLMConfig 的配置即可。

import os
from openjiuwen import LLMConfig
from openjiuwen.agent import ReActAgent

llm_config = LLMConfig(
    api_base="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 从环境变量获取 API Key
    model="qwen3.5-omni-plus",
    provider="openai_compatible"
)

agent = ReActAgent(
    llm_config=llm_config,
    system_prompt="你是知识助手，回答简洁清晰。"
)

resp = agent.run("什么是模型蒸馏")
print(resp.content)

进阶实战：自定义工具调用（Function Call）

Agent 的强大之处在于它能使用工具。openJiuwen 提供了非常便捷的 @tool 装饰器，让你无需手写复杂的 JSON Schema 就能注册自定义函数。

下面是一个完整的示例，Agent 可以自主决定何时调用“获取当前时间”或“计算器”工具。

from openjiuwen import LLMConfig
from openjiuwen.agent import ReActAgent
from openjiuwen.tools import tool
from datetime import datetime

# ---------------------- 1. 定义自定义工具 ----------------------

@tool(description="获取当前系统时间，当用户问现在几点、当前时间时调用")
def get_current_time() -> str:
    now = datetime.now()
    return now.strftime("%Y-%m-%d %H:%M:%S")

@tool(description="数学计算器，做加减乘除运算。入参 expression：数学表达式字符串，例如 '123+45*2'")
def calc(expression: str) -> str:
    try:
        # 注意：生产环境中使用 eval 需谨慎，这里仅做演示
        res = eval(expression)
        return f"计算结果 = {res}"
    except Exception as e:
        return f"计算失败：{str(e)}"

# ---------------------- 2. 配置本地 Ollama 大模型 ----------------------
llm_config = LLMConfig(
    api_base="http://127.0.0.1:11434/v1",
    api_key="dummy",
    model="qwen3-8b",
    provider="openai_compatible"
)

# ---------------------- 3. 构建 Agent，注入工具列表 ----------------------
agent = ReActAgent(
    llm_config=llm_config,
    system_prompt="你是具备工具能力的助手，遇到需要计算、获取时间的问题，优先调用对应工具，不要自己瞎猜。",
    tools=[get_current_time, calc]
)

def main():
    print("===== 测试 1：询问当前时间（会自动调用 get_current_time 工具） =====")
    resp1 = agent.run("现在是什么时间？")
    print(resp1.content)

    print("\n===== 测试 2：数学计算（会自动调用 calc 工具） =====")
    resp2 = agent.run("125 乘以 36 再加 100 等于多少？")
    print(resp2.content)

    print("\n===== 测试 3：普通知识问题，不需要调用工具 =====")
    resp3 = agent.run("简单解释什么是 Few-Shot 提示词")
    print(resp3.content)

if __name__ == "__main__":
    main()

关键点说明

  1. 自动解析：@tool 装饰器会自动读取函数的签名和 description，生成标准的 Function Call 描述传给大模型。你不需要手动编写繁琐的 JSON Schema。
  2. 自主决策：ReActAgent 内部会自动完成“思考 -> 判断是否调用工具 -> 执行工具 -> 获取结果 -> 整理输出”的全过程。
  3. 模型要求：使用的模型必须支持 Function Call。Qwen3-8b 及 Qwen3.5 系列都支持此功能。如果使用一些较小的蒸馏模型，可能会发现工具调用能力较弱，这时可以通过优化 system_prompt 来引导模型。

常见踩坑与排查

在实际使用中，你可能会遇到一些问题，以下是常见的排查思路：

  1. Python 版本问题：openJiuwen 要求 Python 3.11 及以上版本。如果导入时报错，请检查你的 Python 版本。
  2. Ollama 连接失败：确保 ollama serve 已经在后台运行，并且防火墙没有阻止 11434 端口。可以在浏览器访问 http://127.0.0.1:11434 测试连通性。
  3. 模型名称错误：代码中的 model 参数必须与你本地 ollama list 看到的模型名称完全一致。
  4. Agent 不调用工具：如果 Agent 总是自己编造答案而不调用工具，尝试在 system_prompt 中加强指令，例如：“如果你不知道答案，或者需要计算，请务必调用工具，严禁编造。”

总结

openJiuwen 的出现，为国内开发者提供了一个高质量、生产级的 AI Agent 开发选项。它不仅在功能上覆盖了多智能体协作、状态持久化等企业级需求，还通过可视化的 Studio 降低了使用门槛。对于想要构建复杂 AI 应用的团队来说，它是一个值得深入探索的工具箱。

如果你想进一步体验，建议从 Docker 部署全套平台开始，结合官方 GitHub 仓库中的更多样例，逐步深入理解 Swarm 蜂群与工具调用的组合玩法。