CLI-Anything 接入 Ollama:用命令行封装本地大模型 REST API 的完整实战指南
【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything
导读
本文基于 CLI-Anything 仓库中 ollama/agent-harness/OLLAMA.md 这一项目专项分析文档,系统讲解如何把 Ollama 这一本地大模型运行时(负责模型下载、量化、GPU/CPU 推理与内存管理)封装为Agent 原生(Agent-Native)的命令行工具cli-anything-ollama。你将掌握:Ollama REST API 的整体结构与端点语义、原生ollamaCLI 与 CLI-Anything 命令组的逐条映射、流式生成与模型拉取的 NDJSON 处理机制、采样参数(options)的传递方式,以及无需启动服务即可运行的测试策略。读完即可在真实环境中完成"服务检测 → 拉取模型 → 文本生成 → 多轮对话 → 向量嵌入 → 模型清理"的完整本地 LLM 工作流。
一、架构总览:Ollama 是"一个端口上的模型服务工厂"
Ollama 的本质是一个本地 LLM 运行时:它通过 REST API 在localhost:11434上提供服务,统一承担模型下载、量化、GPU/CPU 推理和内存管理。CLI-Anything 无需重复实现任何推理逻辑,只做一件事——把已经清晰完备的 REST API 翻译成结构化命令行。
OLLAMA.md 给出了服务端的分层结构:
┌──────────────────────────────────────────────┐ │ Ollama Server │ │ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │ │ │ Model │ │ Generate │ │ Embeddings │ │ │ │ Manager │ │ Engine │ │ Engine │ │ │ └────┬──────┘ └────┬─────┘ └──────┬──────┘ │ │ │ │ │ │ │ ┌────┴─────────────┴──────────────┴───────┐ │ │ │ REST API (port 11434) │ │ │ │ /api/tags /api/generate /api/embed │ │ │ │ /api/pull /api/chat /api/show │ │ │ │ /api/delete /api/copy /api/ps │ │ │ └─────────────────┬───────────────────────┘ │ └────────────────────┼─────────────────────────┘ │ ┌───────────┴──────────┐ │ llama.cpp backend │ │ GGUF model format │ │ GPU/CPU inference │ └──────────────────────┘从架构上可以看出:Model Manager(模型管理)、Generate Engine(文本/对话生成)、Embeddings Engine(向量嵌入)三大能力统一由 REST 层暴露,底层由 llama.cpp 后端驱动、以 GGUF 为模型格式完成 GPU/CPU 推理。这一分层设计直接决定了 CLI 的命令组划分——模型、生成、嵌入各成一族,职责互不混淆。
服务端默认地址与运行前提
从源码层可以印证默认访问方式。在 ollama_backend.py 中定义了:
# Default Ollama server URL DEFAULT_BASE_URL = "http://localhost:11434"同时模块顶部注释明确了两点关键前提:Ollama 运行本地 HTTP 服务器,默认无认证。这意味着本 CLI 面向本地/内网可信场景设计;若连接公网实例,安全认证需要由外部方案(如反向代理)另行处理。
单元测试 test_core.py 也把DEFAULT_BASE_URL == "http://localhost:11434"作为断言固定下来,防止默认地址被意外改动。
运行前提:需要先安装并启动 Ollama(
ollama serve),CLI 本身是REST API 客户端,不内置服务端。这一点在 setup.py 的包描述中同样被强调:"Recommended: Ollama running at http://localhost:11434"。
二、CLI 策略:REST API Wrapper 的四块拼图
Ollama 原生 CLI(ollama run、ollama serve等)面向人类交互,而 CLI-Anything 的目标是让AI Agent 与重度终端用户能够以"一条命令一个动作、输出机器可解析"的方式驱动 Ollama。因此 OLLAMA.md 确立了四层实现策略:
- requests—— 全部 API 调用的 HTTP 客户端;
- Streaming NDJSON—— 生成与模型拉取过程中的流式增量输出;
- Click CLI—— 与 API 面一一对应的结构化命令组;
- REPL—— 面向探索性使用的交互模式。
这四点在代码中一一对应。安装声明见 setup.py:
install_requires=[ "click>=8.0.0", "prompt-toolkit>=3.0.0", "requests>=2.28.0", ],click承担全部命令组/参数解析;requests承担 HTTP;prompt-toolkit为可选依赖,仅 REPL 模式需要(提供 tab 补全与历史记录);- Python 版本要求
>=3.10,支持 3.10 / 3.11 / 3.12。
安装方式:在 setup.py 所在目录执行pip install -e .(可编辑安装),或发布到 PyPI 后pip install cli-anything-ollama。控制台入口在 setup.py 中注册:
entry_points={ "console_scripts": [ "cli-anything-ollama=cli_anything.ollama.ollama_cli:main", ], },单一 HTTP 封装模块:所有网络请求的唯一出口
仓库把全部"发请求"的职责收敛在 ollama_backend.py 这一个模块里,业务层(models / generate / embeddings / server)只调用它,绝不直接触碰requests。这保证了统一超时、统一错误归一化。
| 函数 | 对应能力 | 超时(秒) |
|---|---|---|
api_get(base_url, endpoint, ...) | GET 请求,如/api/tags、/api/ps、/ | 30 |
api_post(base_url, endpoint, data, ...) | POST 请求,如/api/show、/api/generate | 30 |
api_delete(base_url, endpoint, data, ...) | DELETE 请求,如/api/delete | 30 |
api_post_stream(base_url, endpoint, data, ...) | 流式 POST,逐行解析 NDJSON | 300 |
is_available(base_url) | 探测/是否返回 200 | 5 |
值得注意的细节(可从源码确认):
- URL 拼接容错:
f"{base_url.rstrip('/')}{endpoint}"会先剥掉 base URL 末尾的斜杠再拼端点,因此传http://localhost:11434/与不带斜杠等价——test_core.py 专门验证了这一行为。 - 响应内容协商:
/端点返回纯文本而非 JSON,因此 api_get 会检查content-type:JSON 才resp.json(),纯文本则包装成{"status": "ok", "message": ...}。 - 空响应兜底:
204 No Content(如/api/copy、/api/delete成功)或无内容时返回{"status": "ok"},见 test_core.py。 - 流式模式:api_post_stream 使用
stream=True逐行读取并json.loads,同时跳过空行(NDJSON 中常见的分隔空行),默认超时拉长到 300 秒以容忍长时间生成或大模型下载。 - 错误归一化:连接失败、HTTP 错误、超时都被归一化为携带可读提示的
RuntimeError。连接失败时提示"Is Ollama running? Start it with: ollama serve";HTTP 错误信息包含状态码与响应正文。
核心业务层与端点的一一对应
业务层四个模块均以"端点"为单位封装函数,映射关系清晰:
| 模块 | 函数 | 端点 | 说明 |
|---|---|---|---|
| models.py | list_models | GET /api/tags | 列出本地模型 |
show_model | POST /api/show | 模型详情(参数/模板/许可) | |
pull_model | POST /api/pull | 流式下载模型(stream开关) | |
delete_model | DELETE /api/delete | 删除模型 | |
copy_model | POST /api/copy | 复制/重命名模型 | |
running_models | GET /api/ps | 列出内存中已加载模型 | |
| generate.py | generate | POST /api/generate | 补全式文本生成 |
chat | POST /api/chat | 对话式完成 | |
stream_to_stdout | —— | 把流式块写到 stdout 并返回末块 | |
| embeddings.py | embed | POST /api/embed | 生成嵌入向量 |
| server.py | server_status | GET / | 服务存活检查 |
version | GET /api/version | 服务端版本 |
值得注意的细节:pull_model的流式/非流式差异不是仅仅"等待与否",而是超时策略不同——非流式 pull 使用 600 秒超时(models.py),因为它在等待整包下载完成后一次性返回。
OLLAMA.md 整理的完整端点表如下,本文保留并补充方法语义:
| Endpoint | Method | Purpose |
|---|---|---|
/ | GET | Server status check |
/api/tags | GET | List local models |
/api/show | POST | Model details |
/api/pull | POST | Download model (streaming) |
/api/delete | DELETE | Remove model |
/api/copy | POST | Copy/rename model |
/api/ps | GET | Running models |
/api/generate | POST | Text generation (streaming) |
/api/chat | POST | Chat completion (streaming) |
/api/embed | POST | Generate embeddings |
/api/version | GET | Server version |
从代码结构看,
/api/show、/api/copy、/api/embed、/api/delete等需要携带请求体的操作统一使用 POST/DELETE + JSON body 的形态,/api/tags、/api/ps、/api/version等无状态查询则用 GET,与 Ollama 官方 API 约定一致。
三、命令映射:原生 Ollama CLI → cli-anything-ollama
OLLAMA.md 给出了最核心的对照表——帮助熟悉ollama命令的用户零成本迁移。仓库实现中,所有子命令通过 Click 的@cli.group()/@command注册在 ollama_cli.py 中,命令组为model、generate、embed、server、session五个族:
| Ollama CLI | CLI-Anything |
|---|---|
ollama list | model list |
ollama show <name> | model show <name> |
ollama pull <name> | model pull <name> |
ollama rm <name> | model rm <name> |
ollama cp <src> <dst> | model copy <src> <dst> |
ollama ps | model ps |
ollama run <model> <prompt> | generate text --model <name> --prompt "..." |
| (no equivalent) | generate chat --model <name> --message "..." |
| (no equivalent) | embed text --model <name> --input "..." [--input "..."] |
ollama serve | (external — must be running) |
这张表揭示了 CLI-Anything 相对原生 CLI 的三点增量:
- 显式拆分了补全与对话:原生
ollama run是混合入口;CLI-Anything 将/api/generate与/api/chat拆成generate text/generate chat两条命令,语义更精确,更贴合 Agent 需要明确指定 API 形态的场景。 - 新增嵌入通道:原生 CLI 并无
embed命令,本 CLI 补上了对/api/embed的直接命令行访问。 - 服务端保持外置:
ollama serve属于守护进程职责,本 CLI 不替代、不内嵌,只通过server status/server version探测其状态。
全局选项:--json与--host
整个 CLI 提供两个全局级选项,在 ollama_cli.py 的根命令上声明:
--json:开启机器可读输出,全局变量_json_output会贯穿所有子命令;--host <URL>:覆盖默认的http://localhost:11434,用于连接远程/自定义端口实例。
--host的值会写入全局_host,并被各子命令透传给后端函数。交互式 REPL 内同样可执行带--host的命令来切换会话目标。
四、模型参数(options):CLI 层可调采样旋钮
OLLAMA.md 列出 CLI 已暴露的采样参数,下表保留并补充了含义与取值边界:
| Parameter | Type | Description |
|---|---|---|
temperature | float | 采样温度(0.0-2.0),越高越发散 |
top_p | float | Nucleus(核)采样阈值,保留累计概率达 p 的最小 token 集 |
top_k | int | Top-k 采样,仅从概率最高的 k 个 token 中采样 |
num_predict | int | 生成的最大 token 数 |
repeat_penalty | float | 重复惩罚系数 |
seed | int | 随机种子,用于可复现输出 |
stop | list[str] | 停止序列列表 |
从 CLI 代码看,temperature、top_p、num_predict三项已经直接映射为命令参数。以 generate text 为例:
@generate.command("text") @click.option("--model", "-m", "model_name", required=True, help="Model name") @click.option("--prompt", "-p", required=True, help="Input prompt") @click.option("--system", "-s", default=None, help="System message") @click.option("--no-stream", is_flag=True, help="Return complete response instead of streaming") @click.option("--temperature", type=float, default=None, help="Sampling temperature") @click.option("--top-p", type=float, default=None, help="Top-p sampling") @click.option("--num-predict", type=int, default=None, help="Max tokens to generate")参数收集逻辑为"仅当用户显式给出才写入 options",未给出的选项保持None,不进请求体,从而交由模型自身的默认 Modelfile 参数决定:
options = {} if temperature is not None: options["temperature"] = temperature if top_p is not None: options["top_p"] = top_p if num_predict is not None: options["num_predict"] = num_predict这条"按需注入"策略最终在请求构造时体现为data["options"] = options(见 generate.py),并经由底层传给 llama.cpp 采样器。
测试佐证:test_core.py 的test_generate_builds_correct_payload断言了generate("http://localhost:11434", "llama3.2", "Hello", system="Be helpful", options={"temperature": 0.5}, stream=False)生成的请求体确实包含model、prompt、system、options.temperature与stream=False——这证明 options 是从 CLI 一路无损透传到 HTTP 请求体的。
提示:
top_k、repeat_penalty、seed、stop虽在 API 层受支持(后端直接接受任意options字典),但当前 CLI 尚未为其提供专属 flag。如需使用,可从代码结构看需要通过扩展options或直接构造后端调用来注入,这与文档"Model Parameters"列表的"API 能力全集"定位一致。
流式 vs 非流式:如何取舍
generate text与generate chat都提供--no-stream开关,且默认是流式输出(逐 token 打印,实时可见)。此外还存在第三条隐含路径:--json与流式互斥——当_json_output为真时,即使不加--no-stream,代码也会强制走非流式一次性取整段 JSON,见 ollama_cli.py。
流式块最终由 stream_to_stdout 处理:它会区分两种响应形态(/api/generate用顶层response字段、/api/chat用message.content字段),将 token 逐个写入 stdout 并 flush,同时在遇到done: true的末块时保存含total_duration、eval_count等元数据的最终结果。
五、逐命令实战:从拉模型到清理的完整闭环
下面以 README.md 中记录的示例工作流为主线,逐条给出可复制命令并解释底层行为。
1. 服务探测与版本确认
cli-anything-ollama server status cli-anything-ollama server versionserver status命中GET /;若服务未启动,后端会把连接失败转成 RuntimeError,CLI 层捕获后在 stderr 输出Error: ...并以退出码 1 结束(非 REPL 模式)。这是 Agent 调用任何其他命令前应执行的第一条"健康检查"。
2. 拉取模型
# 默认流式拉取,实时显示进度条 cli-anything-ollama model pull llama3.2 # 非流式,等待完成后一次性返回 cli-anything-ollama model pull llama3.2 --no-stream流式拉取由 ollama_cli.py 驱动:循环消费pull_model(..., stream=True)产出的状态块,仅在状态字符串变化时打印一行(避免刷屏),并在total > 0时绘制由█/░组成的 30 格 ASCII 进度条与百分比。遇到块内带error字段则抛出 RuntimeError 中断。
测试佐证:test_core.py 模拟了pulling manifest → downloading(500/1000) → downloading(1000/1000) → verifying sha256 digest → writing manifest → success的典型拉取序列,断言命令以 0 退出且输出Done;同时test_pull_streaming_error验证中途{"error": "disk full"}会令命令以退出码 1 失败——这确认了 CLI 对下载失败的显式处理。
3. 查看模型
cli-anything-ollama model list # 列出本地模型(表格:NAME/SIZE/MODIFIED) cli-anything-ollama model show llama3.2 # 详情:parameters/template/details cli-anything-ollama model ps # 当前已加载进内存的模型model list命中GET /api/tags。空列表时给出友好提示No models installed. Pull one with: model pull <name>,不会报错(见 ollama_cli.py)。model ps命中GET /api/ps,输出列包含 NAME / SIZE / PROCESSOR(取自size_vram,表示显存占用)/ UNTIL(expires_at,模型卸载时间),可直观判断哪些模型驻留内存。model show返回的details中包含format: gguf、family、parameter_size、quantization_level等字段——这也是确认模型文件底细的最快途径。测试佐证见 test_core.py,其中test_show_nonexistent_model断言对不存在模型执行 show 会收到Ollama API error 404 on POST /api/show并以退出码 1 结束。
4. 文本补全(generate text)
# 流式(默认) cli-anything-ollama generate text --model llama3.2 --prompt "Write a haiku about coding" # 带系统提示词与采样参数 cli-anything-ollama generate text --model llama3.2 \ --prompt "Explain quantum computing" \ --system "You are a helpful physics tutor" \ --temperature 0.7 --top-p 0.9 --num-predict 256 # 非流式,适合脚本化消费 cli-anything-ollama generate text --model llama3.2 \ --prompt "Say hello" --no-stream底层对应 generate.py 的generate():请求体包含model、prompt、stream,可选注入system、template、context、options。流式时每个块是{"response": "...", "done": false}形态;最后一个done: true块附带total_duration、eval_count、load_duration等性能元数据。
5. 多轮对话(generate chat)——原生 CLI 没有的能力
# 单轮 cli-anything-ollama generate chat --model llama3.2 --message "user:Hello!" # 显式多轮(按 role:content 逐个给出,可重复) cli-anything-ollama generate chat --model llama3.2 \ --message "user:What is Python?" \ --message "user:How does it compare to JavaScript?" # 从 JSON 文件读取 messages 数组 cli-anything-ollama generate chat --model llama3.2 --file messages.json # 续接本轮会话历史 cli-anything-ollama generate chat --model llama3.2 \ --message "user:Tell me more" --continue-chatchat 的消息构造规则(源码层面确认于 ollama_cli.py):
- 每个
--message必须包含:分隔符,冒号前是 role(如user/assistant/system),冒号后是内容,role:content中多余冒号只切分第一处; - 格式非法(无冒号)会抛出
ValueError,测试test_generate_chat_bad_format验证了以退出码 1 失败的行为; - 两者都不提供(既无
--message也无--file)同样报错; --file优先级更高,直接从 JSON 文件读取[{"role": ..., "content": ...}, ...]数组,详见测试 test_core.py。
会话记忆机制:CLI 维护进程级全局_chat_history(ollama_cli.py)。流式 chat 完成后,会把本轮完整消息与助手回复写入历史(ollama_cli.py),供--continue-chat或session history使用。
6. 向量嵌入(embed text)——原生 CLI 没有的能力
# 单条文本 cli-anything-ollama embed text --model nomic-embed-text --input "Hello world" # 批量嵌入:重复 --input 即可,一次请求返回多条向量 cli-anything-ollama embed text --model nomic-embed-text \ --input "First text" --input "Second text"底层 embeddings.py 请求POST /api/embed,input既可为字符串也可为字符串列表。CLI 层做了智能判定:只给一个--input时发字符串,多个时聚合为列表发送(ollama_cli.py)。人类可读输出会显示模型名、向量维度(Dimensions)、向量条数,并预览首个向量的前 5 个值(6 位小数)——方便快速核对嵌入模型是否按预期工作。对应测试见 test_core.py。
注意:嵌入必须使用支持嵌入任务的模型(如
nomic-embed-text),普通对话模型无法产出有效嵌入向量。
7. 复制与清理
cli-anything-ollama model copy llama3.2 my-llama # 复制出新名字(204 空响应 → ok) cli-anything-ollama model rm llama3.2 # 删除模型释放磁盘copy与rm成功时返回{"status": "ok"}(204 无内容兜底),CLI 会打印Copied ... → .../Deleted: ...确认信息。
8. 会话状态自省
cli-anything-ollama session status # 显示 host / last_model / chat_history_length / json_output cli-anything-ollama session history # 打印当前进程内的 chat 历史(单条 >200 字符自动截断)六、双输出模式:人类可读表格与 Agent 可解析 JSON
所有命令天然支持两种输出形态(见 README.md "Output Formats" 一节,其核心机制在 output()):
- 人类可读(默认):表格(
model list的 NAME/SIZE/MODIFIED)、层级化键值打印(_print_dict/_print_list递归缩进)、进度条与彩色提示; - 机器可读(
--json):顶层--json开启后,数据经json.dumps(data, indent=2, default=str)输出为标准 JSON,供 Agent 用json.loads直接解析。
# 人类输出 cli-anything-ollama model list # Agent 消费的 JSON 输出 cli-anything-ollama --json model list cli-anything-ollama --json server status一个易被忽略的设计是:错误信息也会随--json结构化。handle_error 装饰器在 JSON 模式下把异常序列化为{"error": "...", "type": "runtime_error"|"<异常类名>"}输出到 stdout,非 JSON 模式则走 stderr 打印Error: ...;无论哪种模式,非 REPL 环境下都以退出码 1 结束。这样 Agent 同时拥有三种判断依据:退出码、stdout(JSON)与 stderr(人类错误)。
测试 test_core.py 的test_generate_text_connection_error_json即验证了--json下 RuntimeError 会产出含type: runtime_error的 JSON。
七、REPL 交互模式与自定义 Host
交互式 REPL
不带子命令直接运行即进入 REPL:
cli-anything-ollamaREPL 由 repl() 实现,基于prompt-toolkit的会话皮肤(ReplSkin,定义于 repl_skin.py)。特性包括:
- 启动时打印版本横幅(
ollama, version1.0.1); - 输入行解析使用
shlex.split,支持带空格的引号字符串(如generate text --model llama3.2 --prompt "hello world");解析失败时降级为简单split; - REPL 内直接复用同一
cli对象(cli.main(args, standalone_mode=False)),因此 REPL 中所有命令与一次性模式行为一致; - 特殊命令
quit/exit/q退出、help显示命令速查表; - 命令组速查(REPL help 内容):
model:list|show|pull|rm|copy|psgenerate:text|chatembed:textserver:status|versionsession:status|history
连接远程/非默认实例
Ollama 默认监听本机 11434。若远程部署(如局域网内的 GPU 宿主机),用--host指定:
cli-anything-ollama --host http://192.168.1.100:11434 model list cli-anything-ollama --host http://192.168.1.100:11434 --json generate text \ --model llama3.2 --prompt "Hello"每次进程启动时的 host 由--host决定,REPL 会话中也可切换。
八、Agent 编程化调用规范
当 AI Agent 或自动化脚本把cli-anything-ollama当作子进程调用时,README.md 给出五条纪律,也是仓库单元测试所固化的契约:
- 始终加
--json获取可解析输出; - 检查退出码——0 成功,非 0 失败;
- 失败时解析 stderr获取错误信息(JSON 模式下错误同时出现在 stdout 的
error字段); - 对 generate/chat 使用
--no-stream一次性拿完整响应,避免逐 token 半成品; - 在其他命令前先
server status确认服务在线,可提前捕获连接类 RuntimeError。
完整 Agent 工作流示例
# ① 健康检查 cli-anything-ollama --json server status # ② 拉取模型(若本地缺失) cli-anything-ollama model pull llama3.2 # ③ 文本补全(非流式,JSON 消费) cli-anything-ollama --json generate text \ --model llama3.2 --prompt "Write a haiku about coding" --no-stream # ④ 多轮对话(脚本化带上下文) cli-anything-ollama --json generate chat \ --model llama3.2 \ --message "user:What is Python?" \ --message "user:How does it compare to JavaScript?" \ --no-stream # ⑤ 检索增强所需的嵌入向量 cli-anything-ollama --json embed text \ --model nomic-embed-text --input "Hello world" # ⑥ 资源巡检 cli-anything-ollama --json model ps # ⑦ 按需清理 cli-anything-ollama model rm llama3.2九、测试策略:两级隔离验证
OLLAMA.md 规划的两级测试在仓库中均有落地实现,测试说明见 tests/TEST.md。
第一级:单元测试(test_core.py),无需 Ollama 服务
通过unittest.mock.patch替换requests.get/post/delete或核心模块的api_*函数,再以 Click 官方CliRunner驱动 CLI,覆盖:
- URL 构造:
api_get("http://localhost:11434/", "/api/tags")实际请求http://localhost:11434/api/tags(尾斜杠被剥离); - 默认地址常量:
DEFAULT_BASE_URL被断言锁定; - 输出格式化:
_format_size(0) == "0 B"、_format_size(2048) == "2.0 KB"、GB 级换算等; - CLI 参数解析:每个命令组的
--help均验证含全部子命令名;--host、--json全局开关注入会话状态; - 会话状态管理:
session status/session history的默认值与空历史行为; - 错误处理路径:连接错误 → RuntimeError → 退出码 1;JSON 模式下产出
{"error": ..., "type": ...}; - 请求体正确性:mock 后断言
generate/chat/embed/copy/delete各自构造的 JSON payload 字段完整正确(test_core.py); - 流式解析:构造
iter_lines()的 NDJSON 字节序列,验证api_post_stream正确产出 dict 块并跳过空行。
运行:
python -m pytest cli_anything/ollama/tests/test_core.py -v第二级:端到端测试(test_full_e2e.py),要求真实 Ollama 服务
按 OLLAMA.md 的 Test Coverage Plan,E2E 流程覆盖:列表模型 → 拉取一个小模型 → 文本生成 → 对话补全 → 查看模型信息 → 嵌入 → 删除模型。运行前需确保ollama serve已启动:
python -m pytest cli_anything/ollama/tests/test_full_e2e.py -v全量执行:
python -m pytest cli_anything/ollama/tests/ -v十、与 Agent 生态的衔接:SKILL 文件
在 CLI-Anything 的项目语境里,每个 CLI 都配套一份供 LLM/Agent 消费的 SKILL.md。其 YAML front-matter 声明了技能名与一句话描述——"Command-line interface for Ollama - Local LLM inference and model management via Ollama REST API",正文按"Installation → Usage → Command Groups → Examples"组织。它与本文讲解的 OLLAMA.md 属于同一套代码的两个互补视图:
- OLLAMA.md(SOP 文档):面向维护者与研究者,解释架构、API 映射、参数语义与测试策略;
- SKILL.md(技能文档):面向 Agent 运行时,只保留"何时调用哪个命令"的最小行动指令。
二者共同服务于 CLI-Anything 的核心理念——让软件 Agent 原生化(Making Software Agent-Native):以稳定、可解析、可测试的 CLI 作为 Agent 与本地大模型之间的标准接口。
十一、快速上手指南(速查)
环境:Python 3.10+;Ollama 已安装并以ollama serve运行在localhost:11434。
安装:
pip install click requests prompt_toolkit # 运行依赖 pip install -e . # 在 ollama/agent-harness 目录执行(开发安装) # 或从 PyPI: pip install cli-anything-ollama常用命令一览:
cli-anything-ollama --help # 总帮助 cli-anything-ollama server status # 健康检查 cli-anything-ollama model list # 本地模型列表 cli-anything-ollama model pull llama3.2 # 流式拉取 cli-anything-ollama generate text --model llama3.2 --prompt "Hello" # 流式生成 cli-anything-ollama generate chat --model llama3.2 --message "user:Hi" # 对话 cli-anything-ollama embed text --model nomic-embed-text --input "Hi" # 嵌入 cli-anything-ollama --json model list # Agent 友好 JSON cli-anything-ollama --host http://192.168.1.100:11434 model list # 远程实例 cli-anything-ollama # 进入 REPL测试:
python -m pytest cli_anything/ollama/tests/test_core.py -v # 无需服务 python -m pytest cli_anything/ollama/tests/test_full_e2e.py -v # 需 Ollama 运行结语
OLLAMA.md 展示的是一条被反复验证的工程范式:面对"服务已具备优良 REST API"的工具,Agent-Native 化的最优解不是再造轮子,而是写一个薄而严谨的 API Wrapper。cli-anything-ollama以五个命令组、单一 HTTP 封装模块、双输出模式与两级测试,把本地 LLM 的完整生命周期——拉取、管理、推理、对话、嵌入、清理——收敛成了可编排、可断言、可被任何 Agent 消费的标准接口。理解这套代码的读者,可以把它当作一个高质量模板,迁移到任意具备 REST API 的桌面软件或本地服务上。
【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考