Skip to content

Recuperación de estructura: restaurar texto plano como Markdown ​

💡 Resumen en una frase: usa Jev para convertir texto plano a Markdown — determina los saltos de línea y los tipos de bloque, deja que el código una las líneas y añada las marcas Markdown, y no dejes que el ordenamiento del formato se convierta sin querer en una reescritura del contenido.

Qué podrás hacer al terminar ​

  • Encontrar en el texto plano las oraciones partidas por saltos de línea forzados.
  • Explicar por qué este ejemplo necesita dos solicitudes: primero unir líneas y luego clasificar.
  • Distinguir cuerpo de texto, títulos, listas, citas, código y bloques de aviso.
  • Validar los resultados comparando con el texto original y revisando la baja confianza, en lugar de fijarte solo en si el formato queda bonito.

Por qué usar Jev en lugar de dejar que un modelo generativo reescriba directamente ​

Las dos rutas persiguen objetivos distintos. Esta lección solo trata el ejemplo oficial de autoformat y no hace un ranking de la calidad de todos los modelos a partir de él.

Punto de verificaciónRuta de generación directa de MarkdownRuta de Jev de este ejemplo
Origen del cuerpo de texto❌ Hay que verificar si el proceso de generación modifica la redacción✅ El renderizador usa los bloques de texto de entrada
Tarea del modelo❌ Decide la estructura y genera texto a la vez✅ Responde preguntas acotadas sobre saltos de línea y tipos de bloque
Generación del formato❌ El modelo produce el Markdown✅ El código añade las marcas
Incertidumbre❌ Hay que diseñar aparte un método de verificación✅ Se conserva la información de probabilidad del resultado del juicio

Esto no es una conversión sin pérdida byte a byte. El preprocesamiento oficial normaliza los espacios en blanco, elimina los espacios al inicio y al final de las líneas y añade espacios al unir líneas; al renderizar también se añaden marcas Markdown nuevas.

Tu problema actual ​

El correo copiado conserva los saltos de línea, pero perdió los títulos y las viñetas. Si fusionas directamente todas las líneas adyacentes, las listas se incrustan en la oración anterior; si conservas línea por línea, un párrafo normal acaba hecho pedazos.

Primero reduce el problema: ¿esta línea es la continuación de una oración cortada a mitad en la línea anterior? Eso está más cerca de la decisión que realmente debes tomar que juzgar «¿es el mismo párrafo?».

Cuándo usar esta técnica ​

Adecuado para texto plano cuyo cuerpo sigue intacto pero que perdió las marcas de estructura. La demo oficial es un memorándum de migración de un sistema de compilación.

No es una herramienta de OCR, corrección de hechos ni relleno de contenido. Si la entrada en sí tiene caracteres faltantes, orden alterado o la indentación del código ya está dañada, conviene conservar el original y organizar una revisión humana; no se puede prometer restaurar automáticamente la intención original del autor.

🎒 Preparativos antes de empezar ​

Primero entiende el tipo de pregunta Choice y el tipo de pregunta Noul. El código de esta lección se toma literalmente del ejemplo oficial de Structure recovery; copiándolo en orden tal cual funciona.

Comando oficial de instalación (cooksafe es la biblioteca de herramientas oficial complementaria, que proporciona la caché JsonCache usada en esta lección y los ayudantes de enlaces de Playground):

bash
pip install ipython 'cooksafe>=0.2.0,<0.3.0'

Descarga la caché desde el directorio del ejemplo oficial de autoformat al directorio donde ejecutas el script (la reproducción de las cifras oficiales grabadas depende de ella):

bash
curl -sL -o json_cache.json https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/autoformat/json_cache.json

El código oficial construye el cliente con la variable de entorno TYPESAFE_API_KEY; no escribas una Key real en notas ni artículos; basta con asignar un valor de marcador de posición si solo vas a reproducir la caché (ver el paso 1). El código también importa la funcionalidad de visualización de IPython (usada al final del ejemplo oficial para generar el enlace de Playground); todos los pasos de esta lección se pueden ejecutar en un script Python normal. Si no colocas el archivo de caché, todas las solicitudes son en tiempo real y requieren credenciales válidas.

La caché no equivale a ejecutar gratis cualquier entrada

La caché oficial sirve para reproducir las llamadas de ejemplo que coinciden. Si cambias la entrada o las preguntas, no puedes asumir que seguirá habiendo coincidencia, ni llamar a una reproducción de caché un resultado medido de un modelo nuevo. Esta lección no realizó llamadas en tiempo real de pago.

Sígueme paso a paso ​

Primero aclaremos cómo ejecutarlo: crea un nuevo autoformat.py y pega los bloques de código de cada paso en orden en el mismo archivo, ejecutando python autoformat.py una vez por cada paso completado. El código se toma literalmente del ejemplo oficial; el único ajuste es definir por adelantado la pregunta de comparación del apéndice oficial naive_join_question (el experimento de comparación del paso 3 la usará). Con json_cache.json en su lugar, todas las llamadas de esta lección aciertan en la caché y reproducen literalmente las respuestas y cifras de latencia grabadas por el ejemplo oficial, sin realizar solicitudes reales.

Paso 1: preparar el texto original y definir los límites de la conversión de texto plano a Markdown ​

Por qué: solo fijando el original puedes saber si al final restauraste el formato o cambiaste el contenido sin darte cuenta.

Pega el código del Setup oficial — cliente, caché, versión del modelo:

python
import os
import re
import urllib.request
from pathlib import Path
from time import perf_counter

from cooksafe import JsonCache, make_playground_link
from IPython.display import Markdown, display
from typesafe_sdk import Choice, Noul, NoulCriteria, TypeSafeClient

TYPESAFE_MODEL = "jev-1.12"
client = TypeSafeClient(api_key=os.environ["TYPESAFE_API_KEY"], timeout=120.0)
json_cache = JsonCache(Path("json_cache.json"))

os.environ["TYPESAFE_API_KEY"] da error directamente si la variable no está configurada. Basta con asignar un valor de marcador de posición si solo vas a reproducir la caché, por ejemplo export TYPESAFE_API_KEY=cache-only — un acierto de caché no realiza solicitudes reales.

Luego pega el código oficial de descarga del texto original (@json_cache hace que esta descarga también sea reproducible):

python
DOCUMENT_URL = (
    "https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/autoformat/build-memo.txt"
)


@json_cache
def fetch_document(url: str) -> str:
    request = urllib.request.Request(url, headers={"User-Agent": "typesafe-cookbook/1.0"})
    with urllib.request.urlopen(request) as response:
        return response.read().decode()


RAW = fetch_document(DOCUMENT_URL)
print(RAW[:560])

Ejecuta python autoformat.py.

Deberías ver: el inicio de un memorándum sin marcas Markdown de títulos ni listas, no un artículo ya formateado:

text
Migration to the new build system

Hi everyone, quick heads up about the build system migration that is
happening next week. We have been running the new pipeline in shadow
mode for three weeks and the results look solid, so it is time to
make the switch for real.

Más adelante hay: un subtítulo What changes for you, un bun run build en línea propia, dos listas sin viñetas y un párrafo de advertencia sin ninguna marca — las marcas de títulos y listas se perdieron todas, pero las líneas vacías siguen ahí (el paso 2 usará justamente esta evidencia).

En el primer ejercicio no sustituyas la entrada ni modifiques las reglas de clasificación; recorre primero el ejemplo público. Todos los juicios posteriores giran en torno a este texto original build-memo.txt.

Paso 2: conservar la evidencia de las líneas vacías y examinar los saltos de línea ​

Por qué: las líneas vacías son información estructural que el código puede leer directamente, no hace falta que el modelo vuelva a adivinar.

Pega el código oficial de to_lines y de numeración de líneas. Normaliza los espacios en blanco, conserva la marca de si existe una línea vacía entre textos adyacentes y asigna a las líneas no vacías números con prefijo L:

python
def to_lines(text: str) -> list[dict]:
    lines, gap = [], False
    for raw in text.split("\n"):
        stripped = re.sub(r"[\t ]+", " ", raw).strip()
        if not stripped:
            gap = bool(lines)  # a leading blank is not a break
            continue
        lines.append({"text": stripped, "gap": gap})
        gap = False
    return lines


def tag(items: list[dict], prefix: str) -> str:
    return "\n".join(
        f"{chr(10) if item['gap'] else ''}{prefix}{i:03d}| {item['text']}"
        for i, item in enumerate(items)
    )


def line_id(i: int) -> str:
    return f"L{i:03d}"


def block_id(i: int) -> str:
    return f"B{i:03d}"


LINES = to_lines(RAW)
print(f"{len(LINES)} non-blank lines. The model sees, e.g.:")
print("\n".join(tag(LINES, "L").splitlines()[19:24]))

Ejecuta.

Deberías ver (salida del ejemplo oficial):

text
28 non-blank lines. The model sees, e.g.:
L013| The cutover touches three teams, so check whether you are on this
L014| list before you plan anything for Monday:
L015| The platform team
L016| The web client team
L017| Whoever still owns the release tooling

El ejemplo oficial tiene 28 líneas no vacías — esto es solo un punto de verificación de esa entrada, no una cantidad que tu propio documento deba alcanzar. El modelo lee el texto con numeración L, y las preguntas y respuestas citan las líneas por número.

Paso 3: usar Noul para decidir si se continúa una oración ​

Por qué: primero hay que restaurar las oraciones partidas por saltos de línea forzados, para que la clasificación de bloques posterior tenga la entrada correcta.

Pega el código oficial de construcción de preguntas del Pass 1. Cada par de líneas adyacentes no separadas por una línea vacía corresponde a una pregunta Noul, y todas van en la misma solicitud; naive_join_question es la pregunta de comparación del apéndice oficial, que se usará en el experimento de comparación al final de este paso:

python
def join_question(i: int) -> Noul:
    return Noul(
        instructions=f"Does line {line_id(i)} pick up mid-sentence, continuing a sentence left unfinished at the end of line {line_id(i - 1)}?",
        criteria=NoulCriteria(
            true="The line starts in the middle of a sentence that began on the previous line - the line break tore the sentence apart",
            false="The line begins a new sentence, item, heading, or thought of its own",
        ),
    )


def naive_join_question(i: int) -> Noul:
    return Noul(
        instructions=f"Are lines {line_id(i - 1)} and {line_id(i)} part of the same paragraph?",
        criteria=NoulCriteria(
            true="The two lines belong to the same paragraph of running text",
            false="The two lines belong to different paragraphs or different pieces of content",
        ),
    )

Pega el código oficial de solicitud y unión de líneas — stitch() pone todos los pares de líneas en una sola solicitud, y merge() une en bloques las líneas continuadas según el umbral:

python
@json_cache
def stitch(wording: str = "mid-sentence") -> dict:
    make = join_question if wording == "mid-sentence" else naive_join_question
    questions = {line_id(i): make(i) for i in range(1, len(LINES)) if not LINES[i]["gap"]}
    started = perf_counter()
    response = client.system_one(
        state=tag(LINES, "L"), questions=questions, model=TYPESAFE_MODEL
    )
    return {
        "joins": [
            response.answers[line_id(i)].noul if line_id(i) in response.answers else 0.0
            for i in range(len(LINES))
        ],
        "seconds": round(perf_counter() - started, 2),
        "usage": [response.usage.input_tokens, response.usage.output_tokens],
    }


result = stitch()
print(f"{sum(1 for l in LINES if not l['gap']) - 1} pair questions, one request, "
      f"{result['seconds']}s")
python
JOIN_AFTER_DANGLING, JOIN_AFTER_TERMINAL = 0.2, 0.5


def ends_terminal(text: str) -> bool:
    return re.search(r'[.!?:;…]["\')\]]*$', text) is not None


def merge(joins: list[float]) -> list[dict]:
    blocks = []
    for i, line in enumerate(LINES):
        bar = (
            JOIN_AFTER_TERMINAL
            if i and ends_terminal(LINES[i - 1]["text"])
            else JOIN_AFTER_DANGLING
        )
        if blocks and not line["gap"] and joins[i] >= bar:
            blocks[-1]["text"] += " " + line["text"]
            blocks[-1]["lines"].append(i)
        else:
            blocks.append({"text": line["text"], "lines": [i], "gap": line["gap"]})
    return blocks


blocks = merge(result["joins"])
healed = len(LINES) - len(blocks)
print(f"{len(LINES)} lines -> {len(blocks)} blocks ({healed} line breaks healed)")
for i, block in enumerate(blocks):
    n = len(block["lines"])
    print(f"{block_id(i)}  {n} line{'s' if n > 1 else ' '}  {block['text'][:62]}")

Ejecuta.

Deberías ver (salida grabada oficial, extracto; al reproducir la caché las cifras de latencia también provienen de la grabación):

text
16 pair questions, one request, 0.32s
28 lines -> 17 blocks (11 line breaks healed)
B000  1 line   Migration to the new build system
B001  4 lines  Hi everyone, quick heads up about the build system migration t
B002  1 line   What changes for you
B003  3 lines  The old make targets keep working until the end of the month. 
B004  1 line   bun run build
……
B014  3 lines  If the doctor script reports a red result on the toolchain che
B015  2 lines  As Dana put it in the kickoff, "a migration nobody notices is 
B016  1 line   Thanks, and shout if anything looks off.

El ejemplo oficial de caché combina las líneas 28 en 17 bloques. La salida de una solicitud en tiempo real no garantiza ser idéntica a la caché; ante discrepancias, revisa primero la entrada, la formulación de las preguntas y el modo de uso de la caché, y no cambies directamente los números esperados.

¿Por qué aquí todavía hacen falta reglas de código?

La lógica oficial de fusión distingue si la línea anterior termina con puntuación terminal y usa umbrales distintos (cuando la línea anterior no tiene puntuación terminal usa 0.2; si la tiene, sube a 0.5); no basta con ver que el "contenido está relacionado" para unir dos líneas. Estos umbrales son una elección de ese ejemplo, no el valor óptimo universal para todos los idiomas y documentos.

Experimento de contraste: no cambies la pregunta por "¿pertenecen al mismo párrafo?". El apéndice oficial reejecutó la unión de líneas con naive_join_question —con una pregunta amplia, los elementos de lista del mismo tema obtuvieron 0.77–0.91, la lista se fusionó con la frase introductoria y los 17 bloques se redujeron a 12 bloques:

python
naive = stitch("same-paragraph")
print(f"{'':14}{'mid-sentence':>13}{'same paragraph':>16}")
for i in (15, 16, 17, 20, 21):
    print(f"{line_id(i)}{'':2}{LINES[i]['text'][:36]:<38}"
          f"{result['joins'][i]:>7.2f}{naive['joins'][i]:>13.2f}")
print(f"\nblocks after merge: {len(blocks)} (mid-sentence) vs "
      f"{len(merge(naive['joins']))} (same paragraph)")
text
               mid-sentence  same paragraph
L015  The platform team                        0.22         0.77
L016  The web client team                      0.11         0.81
L017  Whoever still owns the release tooli     0.12         0.78
L020  Delete the old build cache directory     0.08         0.88
L021  Run the doctor script and fix anythi     0.05         0.91

blocks after merge: 17 (mid-sentence) vs 12 (same paragraph)

"¿Es el mismo párrafo?" pregunta por la continuidad temática; "¿es una oración que continúa la línea anterior?" pregunta por el texto mismo. Cuando el juicio alimenta un umbral, la pregunta debe nombrar el hecho más específico —aquí la diferencia entre ambas preguntas es la diferencia entre 17 bloques y 12 bloques.

Paso 4: clasificar con Choice los bloques ya formados ​

Por qué: los bloques solo existen después de que salga el resultado de la unión de líneas, así que la clasificación no puede fusionarse con la primera pasada de síntesis en una misma solicitud.

Pega los criterios de clasificación del Pass oficial 2. Los tipos de bloque incluyen heading, paragraph, list_item, quote, code, callout; la documentación oficial indica que estos tres diccionarios (más el juicio de sí/no del paso de unión) constituyen toda la especificación del clasificador —si quieres adaptarlo a tus propios documentos, lo que se modifica son estas descripciones:

python
TYPE_CRITERIA = {
    "heading": "A short label or title that names the document or the section that follows it - not a full sentence of content",
    "paragraph": "Running prose: one or more complete sentences of explanatory or narrative text",
    "list_item": "One entry in a list of parallel items - an ingredient, a feature, a task, an attendee; reads as one of several sibling entries",
    "quote": "Words attributed to a person or source - quoted speech, a citation, an excerpt someone else wrote",
    "code": "Computer code, a shell command, terminal output, or a config snippet meant to be read verbatim",
    "callout": "A warning, tip, or important note that interrupts the flow to flag something the reader must not miss",
}
HLEVEL_CRITERIA = {
    "title": "The title of the whole document",
    "section": "A major section heading within the document",
    "subsection": "A minor heading nested under a section",
}
CALLOUT_CRITERIA = {
    "note": "Neutral extra information the reader should be aware of",
    "tip": "A helpful suggestion or shortcut that makes things easier",
    "warning": "A caution about something that can go wrong or cause harm",
}

Pega el código oficial de construcción de la pregunta. La misma solicitud de clasificación también pregunta de antemano por el nivel del título, si la lista tiene orden de pasos y la categoría del bloque de aviso —el tipo se desconoce de antemano y esperarlo exigiría un tercer viaje, por eso las preguntas auxiliares van primero; el renderizador solo usa las respuestas auxiliares relevantes para el tipo final del bloque, y no trata todos los juicios auxiliares como etiquetas válidas:

python
HEADING_MAX_CHARS = 90  # longer blocks can't render as headings, so don't ask


def classify_questions(texts: list[str]) -> dict:
    questions = {}
    for i, text in enumerate(texts):
        bid = block_id(i)
        questions[f"type_{bid}"] = Choice(
            instructions=f"What kind of content is block {bid}?", criteria=TYPE_CRITERIA
        )
        if len(text) <= HEADING_MAX_CHARS:
            questions[f"hlevel_{bid}"] = Choice(
                instructions=f"As a heading, what level would block {bid} occupy in this document's structure?",
                criteria=HLEVEL_CRITERIA,
            )
        questions[f"step_{bid}"] = Noul(
            instructions=f"Is block {bid} an instruction in a sequence where the order of the items matters?",
            criteria=NoulCriteria(
                true="It is one step of a procedure - the items around it must happen in order",
                false="Order is irrelevant - it is a loose collection, or not a list item at all",
            ),
        )
        questions[f"callout_{bid}"] = Choice(
            instructions=f"What kind of aside is block {bid}?", criteria=CALLOUT_CRITERIA
        )
    return questions

Pega la solicitud de clasificación oficial y el código de impresión:

python
@json_cache
def classify(texts: list[str], gaps: list[bool]) -> dict:
    tagged = tag([{"text": t, "gap": g} for t, g in zip(texts, gaps)], "B")
    questions = classify_questions(texts)
    started = perf_counter()
    response = client.system_one(state=tagged, questions=questions, model=TYPESAFE_MODEL)
    judgments = []
    for i in range(len(texts)):
        bid = block_id(i)
        type_answer = response.answers[f"type_{bid}"]
        hlevel = response.answers.get(f"hlevel_{bid}")
        judgments.append(
            {
                "type": type_answer.choice,
                "confidence": type_answer.confidence,
                "probabilities": type_answer.probabilities,
                "hlevel": hlevel.choice if hlevel else "section",
                "step": response.answers[f"step_{bid}"].noul,
                "callout": response.answers[f"callout_{bid}"].choice,
            }
        )
    return {
        "judgments": judgments,
        "n_questions": len(questions),
        "seconds": round(perf_counter() - started, 2),
        "usage": [response.usage.input_tokens, response.usage.output_tokens],
    }


classified = classify([b["text"] for b in blocks], [b["gap"] for b in blocks])
for block, judgment in zip(blocks, classified["judgments"]):
    block.update(judgment)
print(f"{classified['n_questions']} questions about {len(blocks)} blocks, one request, "
      f"{classified['seconds']}s\n")
print(f"{'block':<6}{'type':<11}{'conf':<6}{'companion used':<18}text")
for i, b in enumerate(blocks):
    companion = {
        "heading": f"level={b['hlevel']}",
        "list_item": f"step={b['step']:.2f}",
        "callout": f"kind={b['callout']}",
    }.get(b["type"], "-")
    print(f"{block_id(i):<6}{b['type']:<11}{b['confidence']:.2f}  {companion:<18}"
          f"{b['text'][:46]}")

Ejecuta.

Deberías ver (salida grabada oficial, extracto):

text
62 questions about 17 blocks, one request, 0.51s

block type       conf  companion used    text
B000  heading    0.99  level=title       Migration to the new build system
B001  paragraph  0.98  -                 Hi everyone, quick heads up about the build sy
B002  heading    0.75  level=section     What changes for you
B003  paragraph  0.89  -                 The old make targets keep working until the en
B004  code       1.00  -                 bun run build
B005  paragraph  0.90  -                 Generated artifacts no longer need to be commi
……
B014  callout    0.65  kind=warning      If the doctor script reports a red result on t
B015  quote      0.99  -                 As Dana put it in the kickoff, "a migration no
B016  paragraph  0.92  -                 Thanks, and shout if anything looks off.

Cada bloque tiene un tipo y los juicios correspondientes registrados; los bloques de título pueden dar el nivel, y los bloques de lista el juicio de orden. Observa la probabilidad de step de las dos listas: los tres ítems de tareas pendientes están en 0.86–0.90 (el paso 5 los renderizará como lista numerada), y los tres ítems de la lista del equipo están en 0.12–0.16 (renderizados como lista con viñetas). No llames a la API repetidamente para reproducir los números de latencia del documento.

Paso 5: renderizar Markdown y contrastarlo con el original ​

Por qué: que el juicio sea correcto no garantiza que la presentación final cumpla tus necesidades; también hay que revisar el renderizado y el contenido.

Pega el código oficial de renderizado. to_markdown(blocks) agrupa los elementos de lista consecutivos; si la media de probabilidad de step dentro del grupo alcanza 0.5 usa numeración, si no, viñetas, y añade marcadores para títulos, código, citas y bloques de aviso (el código contiene cadenas con triple comilla invertida, por lo que este bloque de código se delimita con un cerco de cuatro comillas invertidas):

python
STEP_THRESHOLD = 0.5
HEADING_MARK = {"title": "#", "section": "##", "subsection": "###"}
CALLOUT_MARK = {"note": "NOTE", "tip": "TIP", "warning": "WARNING"}


def to_markdown(blocks: list[dict]) -> str:
    groups = []
    for b in blocks:
        if b["type"] in ("list_item", "code") and groups and groups[-1][0] == b["type"]:
            groups[-1][1].append(b)
        else:
            groups.append((b["type"], [b]))
    parts = []
    for kind, items in groups:
        if kind == "list_item":
            ordered = sum(b["step"] for b in items) / len(items) >= STEP_THRESHOLD
            parts.append("\n".join(
                f"{n + 1}. {b['text']}" if ordered else f"- {b['text']}"
                for n, b in enumerate(items)
            ))
        elif kind == "code":
            parts.append("```\n" + "\n".join(b["text"] for b in items) + "\n```")
        elif kind == "heading":
            parts.append(f"{HEADING_MARK[items[0]['hlevel']]} {items[0]['text']}")
        elif kind == "quote":
            parts.append(f"> {items[0]['text']}")
        elif kind == "callout":
            parts.append(f"> [!{CALLOUT_MARK[items[0]['callout']]}]\n> {items[0]['text']}")
        else:
            parts.append(items[0]["text"])
    return "\n\n".join(parts) + "\n"


markdown = to_markdown(blocks)
print(markdown)

Ejecuta, lee primero el Markdown impreso y luego mira el resultado renderizado.

Deberías ver (salida grabada oficial, extracto —el párrafo inicial con cuatro saltos de línea duros se sintetizó en uno solo, los comandos entraron en un cerco de código, una de las dos listas lleva numeración y la otra viñetas, y la advertencia sin ningún marcador se convirtió en bloque de aviso):

text
# Migration to the new build system

Hi everyone, quick heads up about the build system migration that is happening next week. We have been running the new pipeline in shadow mode for three weeks and the results look solid, so it is time to make the switch for real.

……
```
bun run build
```
……
- The platform team
- The web client team
- Whoever still owns the release tooling

## Things to do before Monday

1. Update your local toolchain to version 2.4 or later
2. Delete the old build cache directory
3. Run the doctor script and fix anything it flags

> [!WARNING]
> If the doctor script reports a red result on the toolchain check, do not proceed with the migration. Ping the infra channel first and we will sort it out together.

> As Dana put it in the kickoff, "a migration nobody notices is the only kind worth shipping."

Thanks, and shout if anything looks off.

Los títulos ya no se mezclan con los párrafos normales, las listas y los pasos de operación se representan con listas apropiadas, y los comandos del ejemplo se muestran como texto. Los comandos del documento son contenido pendiente de formatear, no operaciones del sistema que debas ejecutar.

Confirma bloque por bloque que la información original siga presente; revisa especialmente los dos puntos antes de las listas, las oraciones que cruzan líneas, los límites de lista y el código. Para los bloques de baja confianza o difíciles de distinguir entre varios tipos, prioriza la revisión manual —en el ejemplo oficial, el bloque con menor confianza es precisamente la frase introductoria de la lista (0.43, con probabilidades paragraph / list_item / callout dispersas en 0.53 / 0.24 / 0.19), y el ejemplo oficial de umbral de revisión marca para revisión humana los bloques cuya confianza de tipo sea inferior a 0.55.

💡 Este es el valor único de Jev

Cada carácter de la salida proviene de la entrada: el modelo solo respondió preguntas estrechas como "¿esta línea continúa una oración?" o "¿qué tipo es este bloque?"; los límites, tipos y marcadores los decide todo el código. Comparado con pedir directamente a un modelo generativo que reescriba —tendrías que buscar además otra forma de comprobar si cambió la redacción por su cuenta.

📋 Prompts mágicos ​

Los dos primeros son plantillas de preguntas SDK copiables para el flujo de esta lección (los marcadores de posición usan 【】; los que llevan ? son opcionales), y los dos últimos son plantillas de texto para verificación manual —ninguno es una prueba del efecto de un modelo ya ejecutado.

📝 Pregunta de unión de líneas (versión Noul) ​

Efecto esperado: cuando necesites unir líneas de tus propios documentos, copia esta pregunta para cada par de líneas adyacentes y ponlas todas en una sola solicitud; escribe el criterio como un hecho del texto, no como continuidad temática.

python
from typesafe_sdk import Noul, NoulCriteria

# 必填项:【i】是当前行号;true/false 是给模型看的判断标准
join_q = Noul(
    instructions=f"Does line {line_id(【i】)} pick up mid-sentence, continuing a "
                 f"sentence left unfinished at the end of line {line_id(【i - 1】)}?",
    criteria=NoulCriteria(
        true="【这一行从上一行没写完的句子中间开始——换行把句子拆断了】",
        false="【这一行自己开始新的句子、条目、标题或意思】",
    ),
)
# 选填项:官方 ends_terminal 只认英文标点,处理中文文档时把全角标点补进正则?
# 输出规范:answer.noul 是「接着上一行」的概率,拼不拼由代码按阈值决定
# 约束条件:
# ✅ 问「是否接续句子」这种窄事实——官方对照:换成「同一段落」,列表项得分 0.77–0.91,17 块并成 12 块
# ✅ 空行隔开的行对跳过不发;上一行结尾有无标点由代码读,两档阈值分开设
# ❌ 别让模型输出拼接后的文本——拼接由代码做,输出每个字都来自输入

✅ Pregunta de tipo de bloque (versión Choice) ​

Efecto esperado: convierte "¿qué contenido es este bloque?" en una pregunta de opción múltiple; para adaptarlo a tus propios documentos, lo que se modifica es el texto de las descripciones —la documentación oficial dice que estos tres diccionarios son toda la especificación del clasificador.

python
from typesafe_sdk import Choice

# 必填项:criteria 的键是类型名,值是给模型看的判断标准
type_q = Choice(
    instructions=f"What kind of content is block {【块编号】}?",
    criteria={
        "heading": "【短标签或标题,命名文档或其后章节——不是完整句子】",
        "paragraph": "【成段散文:一句或多句完整的说明或叙述】",
        "list_item": "【平行条目列表中的一条,读起来是同类的兄弟条目】",
        # 官方还有 quote / code / callout 三类,按同样格式补齐
    },
)
# 选填项:辅助题(标题层级 / 步骤顺序 / 提示块类别)提前放进同一请求,答案只在类型相关时读?
# 输出规范:answer.choice 是类型名;answer.confidence 和 probabilities 接人工复核线
# 约束条件:
# ✅ 每块一题、全部块一次请求——块要等拼行完成才存在,这是第二请求的真实依赖
# ✅ 超过 90 字符的块不问标题层级(官方 HEADING_MAX_CHARS = 90)
# ❌ 别只看最高分标签——概率分散的块(官方示例最低 0.43)送人工复核

⚠️ Comprobar si el original fue reescrito ​

Efecto esperado: limitar el resultado de la verificación a problemas localizables.

text
Rol: corrector de documentos.
Tarea: comparar el original con el Markdown recuperado y comprobar si el cuerpo del texto omite contenido o fue reescrito.
Información de entrada:
### Campos obligatorios
- Original【pegar】
- Markdown recuperado【pegar】
### Campos opcionales
- Reglas de normalización de espacios permitidas【rellenar】? (por ejemplo, "normalizar espacios en línea, eliminar espacios al inicio y al final de la línea, añadir un espacio al unir líneas")
Especificación de salida: listar por posición las diferencias, el tipo de diferencia y el motivo que requiere confirmación humana.
Condiciones de restricción:
✅ Distinguir marcadores Markdown del cuerpo del texto —los marcadores añadidos #, -, > no cuentan como reescritura
✅ Cada diferencia debe citar fragmentos reales, localizables en la posición del original
❌ No completar por cuenta propia el contenido faltante
❌ No afirmar que todas las diferencias son errores

🔧 Comprobar bloques estructurales sospechosos ​

Efecto esperado: procesar solo un límite controvertido y evitar rehacer todo el documento.

text
Rol: inspector de estructura.
Tarea: comprobar el tipo de un bloque de texto y su límite con los bloques adyacentes.
Información de entrada:
### Campos obligatorios
- Bloque anterior【pegar】
- Bloque actual【pegar】
- Bloque siguiente【pegar】
### Campos opcionales
- Situación original de líneas en blanco【describir】?
- Distribución de probabilidad de tipos de ese bloque【pegar】?
Especificación de salida: dar evidencia visible, explicaciones alternativas y sugerencias de revisión humana.
Condiciones de restricción:
✅ Conservar la redacción original y citar fragmentos reales
✅ Distinguir los marcadores explícitos de las conjeturas semánticas, etiquetándolos por separado
❌ No inventar cifras de probabilidad o confianza
❌ No tratar el contenido de bloques de código como instrucciones a ejecutar

Punto de control ✅ ​

  • La reproducción desde caché ejecutó el flujo completo: 28 líneas no vacías → 16 preguntas de unión de líneas en una solicitud → 17 bloques → 62 preguntas de clasificación en una solicitud → salida renderizada, con cifras idénticas a la grabación oficial.
  • El original, los bloques de texto organizados y el Markdown final pueden contrastarse entre sí.
  • Sabe explicar la dependencia secuencial entre la solicitud de unión y la de clasificación, sin afirmar erróneamente que "una sola solicitud lo hace todo".
  • Las listas no se fusionaron por error con la frase introductoria, el código no se ejecutó por error y los niveles de título pasaron revisión humana.
  • Los resultados de caché y las pruebas en tiempo real están claramente diferenciados, sin tomar las cifras del ejemplo del documento como mediciones propias.

Advertencias de errores comunes ​

FenómenoRevisar primero
Varios elementos de lista se fusionan en un párrafoSi la pregunta se cambió por un "mismo párrafo" amplio; si se conservaron las líneas en blanco y las reglas de fusión
Títulos o bloques de aviso no cumplen lo esperadoCotejar las descripciones de clasificación con el contexto del original, no mirar solo la etiqueta con mayor puntuación
Tus cifras difieren de las del ejemploSi la entrada, el modelo, las preguntas y la caché son consistentes; no exigir que una entrada arbitraria reproduzca los resultados del ejemplo
Un bloque de aviso especial se muestra como cita normalSi el lector Markdown de destino admite la sintaxis extendida correspondiente
Se pierde la indentación del códigoEl preprocesamiento oficial normaliza los espacios; no tomar este ejemplo como un restaurador sin pérdida del formato de archivos de código arbitrarios
El juicio de unión de líneas falla en documentos chinosLa expresión regular oficial ends_terminal solo coincide con puntuación inglesa (. ! ? : ; y …); la puntuación de ancho completo debe añadirse por tu cuenta a la clase de caracteres

Resumen de la lección ​

En este ejemplo, la conversión de texto plano a Markdown se dividió en tres tareas: primero juzgar los saltos de línea, luego juzgar el tipo de bloque y, por último, renderizar mediante código. Las dos solicitudes a la API provienen de dependencias reales de entrada, no de añadir viajes para que el resultado sea automáticamente más fiable.

Fuente de esta página: sources/jev/docs/cookbooks/autoformat.md; copia local de la entrada del ejemplo oficial y de la caché: sources/jev/extra/c2-autoformat-build-memo.txt, sources/jev/extra/c2-autoformat-json-cache.json. Las cifras anteriores provienen del ejemplo público y de la verificación contra la caché local (la caché contiene las respuestas grabadas de dos pasadas de unión y una de clasificación), no de una prueba de rendimiento en tiempo real recién iniciada para esta lección.

Avance de la próxima lección ​

La próxima lección verá Pedidos en lenguaje natural: convertirlos en un carrito de compras estructurado, para seguir practicando cómo descomponer un problema de negocio en juicios explícitos y dejar que el programa procese el resultado. También puedes volver a Extracción de valores para contrastar la diferencia entre "identificar información" y "recuperar estructura".

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.