Parse Quickstart 快速上手

本地启动 Cortex，签发开发 token，同步解析 URL，并运行异步解析 job。

这个快速上手从本地 Docker 开始，然后完整调用 Parse。下面的 API 片段是 AI 生成的 Python、JavaScript 和 Java 客户端示例。

1. 启动 Cortex

cd /path/to/cortex
test -f .env || cp .env.local.example .env

docker compose --env-file .env -p cortex-local -f compose.local.yaml \
  --profile docling \
  --profile eval-runtime \
  --profile synthesis-runtime \
  up -d --build

打开 Swagger：http://127.0.0.1:8080/docs。

2. 创建本地 token

import requestsbase_url = "http://127.0.0.1:8080"payload = {    "subject": "cortex-quickstart",    "tenant_id": "tenant_demo",    "roles": ["tenant_admin"],    "expires_in": 3600,}response = requests.post(f"{base_url}/v1/dev/auth/token", json=payload)response.raise_for_status()token = response.json()["access_token"]print(token)

const baseUrl = "http://127.0.0.1:8080";const response = await fetch(`${baseUrl}/v1/dev/auth/token`, {  method: "POST",  headers: { "Content-Type": "application/json" },  body: JSON.stringify({    subject: "cortex-quickstart",    tenant_id: "tenant_demo",    roles: ["tenant_admin"],    expires_in: 3600,  }),});if (!response.ok) throw new Error(await response.text());const { access_token: token } = await response.json();console.log(token);

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample {  static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080");  static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token");  static final HttpClient HTTP = HttpClient.newHttpClient();  static void print(HttpResponse<String> response) {    System.out.println(response.statusCode());    System.out.println(response.body());  }  public static void main(String[] args) throws Exception {    String json = """      {        "subject": "cortex-quickstart",        "tenant_id": "tenant_demo",        "roles": ["tenant_admin"],        "expires_in": 3600      }      """;    HttpRequest request = HttpRequest.newBuilder()      .uri(URI.create(BASE_URL + "/v1/dev/auth/token"))      .header("Content-Type", "application/json")      .POST(HttpRequest.BodyPublishers.ofString(json))      .build();    print(HTTP.send(request, HttpResponse.BodyHandlers.ofString()));  }}

运行后续示例时，把返回的 token 设置为 CORTEX_TOKEN。

3. 查看可用引擎

import osimport requestsBASE_URL = os.getenv("CORTEX_URL", "http://127.0.0.1:8080")TOKEN = os.getenv("CORTEX_TOKEN", "replace_with_token")def auth_headers():    return {"Authorization": f"Bearer {TOKEN}"}response = requests.get(f"{BASE_URL}/v1/parse/engines", headers=auth_headers())response.raise_for_status()data = response.json()print(data)

const BASE_URL = process.env.CORTEX_URL ?? "http://127.0.0.1:8080";const TOKEN = process.env.CORTEX_TOKEN ?? "replace_with_token";const authHeaders = {  Authorization: `Bearer ${TOKEN}`,};const response = await fetch(`${BASE_URL}/v1/parse/engines`, {  headers: authHeaders,});if (!response.ok) throw new Error(await response.text());const data = await response.json();console.log(data);

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample {  static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080");  static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token");  static final HttpClient HTTP = HttpClient.newHttpClient();  static void print(HttpResponse<String> response) {    System.out.println(response.statusCode());    System.out.println(response.body());  }  public static void main(String[] args) throws Exception {    HttpRequest request = HttpRequest.newBuilder()      .uri(URI.create(BASE_URL + "/v1/parse/engines"))      .header("Authorization", "Bearer " + TOKEN)      .GET()      .build();    print(HTTP.send(request, HttpResponse.BodyHandlers.ofString()));  }}

4. 同步解析一个 URL

import osimport requestsBASE_URL = os.getenv("CORTEX_URL", "http://127.0.0.1:8080")TOKEN = os.getenv("CORTEX_TOKEN", "replace_with_token")def auth_headers():    return {"Authorization": f"Bearer {TOKEN}"}payload = {  "sources": [    "https://docs.cognee.ai/core-concepts/overview"  ],  "engine_id": "auto"}response = requests.post(    f"{BASE_URL}/v1/parse/sync",    headers={**auth_headers(), "Content-Type": "application/json"},    json=payload,)response.raise_for_status()data = response.json()print(data['results'][0]['document']['markdown'][:800]);

const BASE_URL = process.env.CORTEX_URL ?? "http://127.0.0.1:8080";const TOKEN = process.env.CORTEX_TOKEN ?? "replace_with_token";const authHeaders = {  Authorization: `Bearer ${TOKEN}`,};const payload = {  "sources": [    "https://docs.cognee.ai/core-concepts/overview"  ],  "engine_id": "auto"};const response = await fetch(`${BASE_URL}/v1/parse/sync`, {  method: "POST",  headers: { ...authHeaders, "Content-Type": "application/json" },  body: JSON.stringify(payload),});if (!response.ok) throw new Error(await response.text());const data = await response.json();console.log(data.results[0].document.markdown.slice(0, 800));

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample {  static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080");  static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token");  static final HttpClient HTTP = HttpClient.newHttpClient();  static void print(HttpResponse<String> response) {    System.out.println(response.statusCode());    System.out.println(response.body());  }  public static void main(String[] args) throws Exception {    String json = """      {        \"sources\": [          \"https://docs.cognee.ai/core-concepts/overview\"        ],        \"engine_id\": \"auto\"      }      """;    HttpRequest request = HttpRequest.newBuilder()      .uri(URI.create(BASE_URL + "/v1/parse/sync"))      .header("Authorization", "Bearer " + TOKEN)      .header("Content-Type", "application/json")      .POST(HttpRequest.BodyPublishers.ofString(json))      .build();    print(HTTP.send(request, HttpResponse.BodyHandlers.ofString()));  }}

5. 运行异步 job

Docling、LlamaParse 或大批量解析建议使用异步模式。

import osimport requestsBASE_URL = os.getenv("CORTEX_URL", "http://127.0.0.1:8080")TOKEN = os.getenv("CORTEX_TOKEN", "replace_with_token")def auth_headers():    return {"Authorization": f"Bearer {TOKEN}"}payload = {  "sources": [    "https://docs.crawl4ai.com/advanced/advanced-features/"  ],  "engine_id": "crawl4ai",  "priority": 5}response = requests.post(    f"{BASE_URL}/v1/parse/jobs",    headers={**auth_headers(), "Content-Type": "application/json"},    json=payload,)response.raise_for_status()data = response.json()print(data)

const BASE_URL = process.env.CORTEX_URL ?? "http://127.0.0.1:8080";const TOKEN = process.env.CORTEX_TOKEN ?? "replace_with_token";const authHeaders = {  Authorization: `Bearer ${TOKEN}`,};const payload = {  "sources": [    "https://docs.crawl4ai.com/advanced/advanced-features/"  ],  "engine_id": "crawl4ai",  "priority": 5};const response = await fetch(`${BASE_URL}/v1/parse/jobs`, {  method: "POST",  headers: { ...authHeaders, "Content-Type": "application/json" },  body: JSON.stringify(payload),});if (!response.ok) throw new Error(await response.text());const data = await response.json();console.log(data);

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample {  static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080");  static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token");  static final HttpClient HTTP = HttpClient.newHttpClient();  static void print(HttpResponse<String> response) {    System.out.println(response.statusCode());    System.out.println(response.body());  }  public static void main(String[] args) throws Exception {    String json = """      {        \"sources\": [          \"https://docs.crawl4ai.com/advanced/advanced-features/\"        ],        \"engine_id\": \"crawl4ai\",        \"priority\": 5      }      """;    HttpRequest request = HttpRequest.newBuilder()      .uri(URI.create(BASE_URL + "/v1/parse/jobs"))      .header("Authorization", "Bearer " + TOKEN)      .header("Content-Type", "application/json")      .POST(HttpRequest.BodyPublishers.ofString(json))      .build();    print(HTTP.send(request, HttpResponse.BodyHandlers.ofString()));  }}

然后轮询通用 job endpoint，并读取 Parse 结果：

import osimport requestsBASE_URL = os.getenv("CORTEX_URL", "http://127.0.0.1:8080")TOKEN = os.getenv("CORTEX_TOKEN", "replace_with_token")def auth_headers():    return {"Authorization": f"Bearer {TOKEN}"}response = requests.get(f"{BASE_URL}/v1/jobs/job_xxx", headers=auth_headers())response.raise_for_status()data = response.json()print(data)

const BASE_URL = process.env.CORTEX_URL ?? "http://127.0.0.1:8080";const TOKEN = process.env.CORTEX_TOKEN ?? "replace_with_token";const authHeaders = {  Authorization: `Bearer ${TOKEN}`,};const response = await fetch(`${BASE_URL}/v1/jobs/job_xxx`, {  headers: authHeaders,});if (!response.ok) throw new Error(await response.text());const data = await response.json();console.log(data);

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample {  static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080");  static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token");  static final HttpClient HTTP = HttpClient.newHttpClient();  static void print(HttpResponse<String> response) {    System.out.println(response.statusCode());    System.out.println(response.body());  }  public static void main(String[] args) throws Exception {    HttpRequest request = HttpRequest.newBuilder()      .uri(URI.create(BASE_URL + "/v1/jobs/job_xxx"))      .header("Authorization", "Bearer " + TOKEN)      .GET()      .build();    print(HTTP.send(request, HttpResponse.BodyHandlers.ofString()));  }}

import osimport requestsBASE_URL = os.getenv("CORTEX_URL", "http://127.0.0.1:8080")TOKEN = os.getenv("CORTEX_TOKEN", "replace_with_token")def auth_headers():    return {"Authorization": f"Bearer {TOKEN}"}response = requests.get(f"{BASE_URL}/v1/parse/jobs/job_xxx/result", headers=auth_headers())response.raise_for_status()data = response.json()print(data)

const BASE_URL = process.env.CORTEX_URL ?? "http://127.0.0.1:8080";const TOKEN = process.env.CORTEX_TOKEN ?? "replace_with_token";const authHeaders = {  Authorization: `Bearer ${TOKEN}`,};const response = await fetch(`${BASE_URL}/v1/parse/jobs/job_xxx/result`, {  headers: authHeaders,});if (!response.ok) throw new Error(await response.text());const data = await response.json();console.log(data);

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample {  static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080");  static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token");  static final HttpClient HTTP = HttpClient.newHttpClient();  static void print(HttpResponse<String> response) {    System.out.println(response.statusCode());    System.out.println(response.body());  }  public static void main(String[] args) throws Exception {    HttpRequest request = HttpRequest.newBuilder()      .uri(URI.create(BASE_URL + "/v1/parse/jobs/job_xxx/result"))      .header("Authorization", "Bearer " + TOKEN)      .GET()      .build();    print(HTTP.send(request, HttpResponse.BodyHandlers.ofString()));  }}

现在你已经把原始 Web 内容转换成了标准化 Markdown，可以继续上传到 Storage 或摄入 Knowledge。