llmextractmapper

April 8, 2026 · View on GitHub

Extract structured fields from text using an LLM; write results to meta. Part of the llm_* semantic ops family.

This operator uses an LLM to extract user-defined fields from each sample's text (or multiple input keys). You provide an output_schema (key → extraction instruction). Results are written to meta[meta_output_key] or to individual meta keys. Supports structured (JSON) and unstructured (e.g. plain text, jsonl) input. Token/cost usage is recorded in meta[llm_semantic_usage] (prompt_tokens, completion_tokens, total_tokens, optional cost_estimate).

使用 LLM 从文本中提取用户定义的结构化字段；结果写入 meta。支持结构化与非结构化输入，并记录 token/cost 用量。

Type 算子类型: mapper

Tags 标签: gpu, vllm, hf, api

🔧 Parameter Configuration 参数配置

name 参数名	type 类型	default 默认值	desc 说明
`input_keys`	list	required	Sample keys to build input text (e.g. `["text"]` or `["query","response"]`).
`output_schema`	dict	required	`{output_key: "extraction instruction"}`.
`api_or_hf_model`	str	`'gpt-4o'`	Model name for API or HuggingFace.
`meta_output_key`	str, optional	`'llm_extract'`	If set, write full result to `meta[meta_output_key]`.
`knowledge_grounding_key`	str, optional	`None`	Optional sample key for per-sample grounding.
`knowledge_grounding_fixed`	str, optional	`None`	Optional fixed grounding string.
`is_hf_model`	bool	`False`	If true, use HuggingFace/Transformers.
`enable_vllm`	bool	`False`	If true, use vLLM backend.
`api_endpoint`	str, optional	`None`	URL endpoint for the API.
`response_path`	str, optional	`None`	Path to extract content from API response.
`system_prompt`	str, optional	`None`	Override default extraction system prompt.
`try_num`	int	`3`	Retries on parse/API failure.
`model_params`	dict	`{}`	Parameters for model init.
`sampling_params`	dict	`{}`	Sampling params (e.g. temperature, top_p).

📊 Effect demonstration 效果演示

The examples below match the unit tests. Concrete field values depend on the model and API; only shape and keys are guaranteed.
下列示例与单元测试场景一致；具体抽取内容随模型与接口变化，文档中仅示意典型结果。

test_extract_default

LLMExtractMapper(
    input_keys=["text"],
    output_schema={
        "topic": "One short phrase: main topic.",
        "sentiment": "One word: positive, negative, or neutral.",
    },
    api_or_hf_model="gpt-4o",
    meta_output_key="llm_extract",
    try_num=2,
)

📥 input data 输入数据

Sample 1: text

The stock market rose today. Investors are optimistic.

Sample 2: text

Bad weather caused delays. Many people were upset.

📤 output data 输出数据

Sample 1: text

The stock market rose today. Investors are optimistic.

meta
llm_extract	{"topic": "stock market / finance", "sentiment": "positive"}
llm_semantic_usage	{"prompt_tokens": …, "completion_tokens": …, "total_tokens": …}

Sample 2: text

Bad weather caused delays. Many people were upset.

meta
llm_extract	{"topic": "weather / travel disruption", "sentiment": "negative"}
llm_semantic_usage	{"prompt_tokens": …, "completion_tokens": …, "total_tokens": …}

✨ explanation 解释

dataset.map(op.process, batch_size=1) fills meta["llm_extract"] with keys from output_schema. When the API returns usage, meta["llm_semantic_usage"] holds token counts (and optional cost).
对每条样本调用 map 后，meta 中写入抽取结果；若接口返回用量，则同时写入 llm_semantic_usage。

test_extract_empty_input

LLMExtractMapper(
    input_keys=["text"],
    output_schema={"topic": "Main topic.", "sentiment": "Sentiment."},
    api_or_hf_model="gpt-4o",
    meta_output_key="llm_extract",
)

📥 input data 输入数据

Sample 1: text

📤 output data 输出数据

Sample 1: text

meta
llm_extract	{"topic": null, "sentiment": null}

✨ explanation 解释

Empty concatenated input skips the LLM call and sets all schema fields to null as in the unit test.
空输入时不调用模型，各字段为 null，与单测一致。

🌐 DashScope / OpenAI-compatible 环境变量

使用阿里云 DashScope OpenAI 兼容模式（REST）时，可只配环境变量，无需在 recipe 里写 key：

export OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export OPENAI_API_KEY=<你的 DashScope API Key>
# 或使用：export DASHSCOPE_API_KEY=<同上>

默认算子模型名为 gpt-4o，在 DashScope 上不可用。若检测到上述兼容 Base URL，会自动改用 qwen-plus（可通过 DASHSCOPE_DEFAULT_MODEL 或 OPENAI_DEFAULT_MODEL 覆盖），或在配置里显式设置 api_or_hf_model: qwen-plus。

OPENAI_API_URL 与 OPENAI_BASE_URL 等价（任选其一）。

📊 Cost / usage 成本与用量

Each sample gets meta[llm_semantic_usage] with:

prompt_tokens, completion_tokens, total_tokens
cost_estimate (optional, when pricing is available)