Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the old one-liner form, and migrate lib/ext/examples/tests/docs accordingly. Co-authored-by: Cursor <cursoragent@cursor.com>
3.6 KiB
3.6 KiB
Official extensions (ext/) — LLM
| Status | Accepted · v0.3 semantic(005:Intelligence Primitive) |
| Date | 2026-09-24 |
| Related | objects.md · ext-agent.md · ext-cli.md · ai-stack.md · doc/next/005.md |
Scope
ext/ai/llm is Marqdo’s intelligence primitive, not an OpenAI SDK wrapper.
Author surface: ask / stream / collect / create / fast / reasoning / prompt_load
Transport: ext/ai/llm/openai.mq.md (+ ollama defaults)
Compat: complete / chat
Import:
---
import:
llm: ext/ai/llm.mq.md
---
Public API
| English | Chinese | Role |
|---|---|---|
## load_env |
## 加载环境 |
Load .env |
## create |
## 创建 |
Factory → LLM handle |
## fast / ## reasoning |
## 快速 / ## 推理 |
Named handles |
## prompt_load / ## prompt / ## prompt_body |
## 加载提示 / ## 提示 / ## 提示正文 |
Prompt artifacts (type: prompt → body) |
## ask (module) |
## 提问 |
Convenience → text (prompt= or path=) |
## collect |
## 收集 |
Events → text |
## stream_result |
## 流式结果 |
Alias of collect |
# llm |
# 大模型 |
Handle ctor (backend= openai-compatible | ollama) |
## ask (method) |
## 提问 |
→ LLMResult map |
## stream |
## 流式 |
→ event list |
## complete / ## chat |
## 运行 / ## 聊天 |
Compat / transport primitive |
Preferred
**answer = > llm.ask prompt="What is Marqdo?"**
*answer*
**model = > llm.create**
**result = > `model`.ask prompt=`prompt`**
*[text](result)*
**fast = > llm.fast**
**events = > `fast`.stream prompt=`prompt`**
**text = > llm.collect events=`events`**
**body = > llm.prompt path="fixtures/prompt-marqdo.md"**
**body2 = > llm.prompt text=`raw`**
LLMResult
| Field | Meaning |
|---|---|
text |
Answer string |
model |
Model id |
finish |
Finish reason (stop, …) |
backend |
e.g. openai-compatible / ollama |
usage |
{prompt_tokens,completion_tokens,total_tokens} |
tokens |
Alias of usage.total_tokens (agent metrics) |
name |
Optional handle tag (fast / reasoning) |
llm_calls |
1 per ask |
tool_calls |
List of OpenAI-shaped tool call objects (empty when none) |
Compat
complete / chat still return a bare string (or event list when stream=True) so ext/ai/agent and older runbooks keep working. New code should use ask / stream / collect.
Environment
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
MARQDO_LLM_FAST_MODEL=...
MARQDO_LLM_REASONING_MODEL=...
OLLAMA_HOST=http://127.0.0.1:11434/v1
Fallbacks: MARQDO_LLM_API_KEY, MARQDO_LLM_BASE_URL, MARQDO_LLM_MODEL. Ctor also accepts api_key= / base_url= / model= / backend=.
Backends
backend= |
Module | Notes |
|---|---|---|
openai-compatible (default) |
ext/ai/llm/openai.mq.md |
Chat Completions HTTP + SSE |
ollama |
defaults in ctor + same transport | Key defaults to ollama; host from OLLAMA_HOST |
Tests
tests/ext/llm-import.mq.mdtests/ext/llm-ctor-offline.mq.mdtests/ext/llm-ask-offline.mq.md(create + collect)tests/ext/llm-stream-offline.mq.mdtests/ext/llm-named-offline.mq.md(fast/reasoning + prompt_load)tests/ext/llm-tool-calls-offline.mq.md(tool_calls_from/ Result field)tests/ext/llm-meta-offline.mq.md·llm-entry-prompt-offline.mq.md- Live:
llm-complete.mq.md·llm-stream-live.mq.md