 Ver na IA do Google
|
 Executar no Google Colab
|
 Veja o código-fonte no GitHub
|
Neste tutorial, você vai trabalhar com um exemplo de extração de dados estruturados, usando a API Gemini para extrair listas de personagens, relacionamentos, coisas e lugares de uma história.
Configuração
pip install -U -q google-generativeai
import pathlib
import textwrap
import google.generativeai as genai
from IPython.display import display
from IPython.display import Markdown
from google.api_core import retry
def to_markdown(text):
text = text.replace('•', ' *')
return Markdown(textwrap.indent(text, '> ', predicate=lambda _: True))
Quando você tiver a chave de API, transmita-a ao SDK. Faça isso de duas maneiras:
- Coloque a chave na variável de ambiente
GOOGLE_API_KEY. O SDK vai selecioná-la automaticamente de lá. - Transmita a chave para
genai.configure(api_key=...)
try:
# Used to securely store your API key
from google.colab import userdata
# Or use `os.getenv('API_KEY')` to fetch an environment variable.
GOOGLE_API_KEY=userdata.get('GOOGLE_API_KEY')
except ImportError:
import os
GOOGLE_API_KEY = os.environ['GOOGLE_API_KEY']
genai.configure(api_key=GOOGLE_API_KEY)
A tarefa de exemplo
Neste tutorial, você vai extrair entidades de histórias em linguagem natural. Por exemplo, abaixo está uma história escrita pelo Gemini.
new_story = False
if new_story:
model = genai.GenerativeModel(model_name='models/gemini-1.5-pro-latest')
response = model.generate_content("""
Write a long story about a girl with magic backpack, her family, and at
least one other charater. Make sure everyone has names. Don't forget to
describe the contents of the backpack, and where everyone and everything
starts and ends up.""", request_options={'retry': retry.Retry()})
story = response.text
print(response.candidates[0].citation_metadata)
else:
story = """In the quaint town of Willow Creek, nestled amidst rolling hills and whispering willows, resided a young girl named Anya. As she stepped out of the creaky wooden door of her modest cottage, her heart skipped a beat with excitement and anticipation. Today was her first day of school, and she couldn't wait to show off her prized possession - a magical backpack.\n\nHanded down to her from her grandmother, the backpack was no ordinary satchel. Its soft, emerald-green fabric shimmered with an ethereal glow, and its leather straps held secrets that only Anya knew. Within its capacious interior lay an enchanted world, filled with wonders that would ignite her imagination and change her life forever.\n\nAnya's parents, kind-hearted Elise and wise-bearded Edward, bid her farewell with warm embraces. "Remember, my dear," whispered her mother, "use your magic wisely and for good." Her father added, "Always seek knowledge, and let the backpack be your trusted companion."\n\nWith a skip in her step, Anya set off towards the town's only schoolhouse. On her way, she passed her best friend, Samuel, a curious and adventurous boy with a mischievous grin. "Hey, Anya," he called out. "Can I see your backpack?"\n\nAnya hesitated for a moment before unzipping the flap and revealing its contents. Samuel's eyes widened in amazement as he peered inside. There, nestled amidst pencils and notebooks, were a shimmering sword, a book of ancient spells, a tiny compass that always pointed north, and a magical key that could open any lock.\n\nTogether, they marveled at the backpack's wonders, promising to keep its secrets safe. As they approached the schoolhouse, Anya noticed a group of older children huddled together, their faces etched with fear. Curiosity getting the better of her, she cautiously approached.\n\n"What's wrong?" she asked.\n\nA tall, lanky boy stepped forward. "There's a monster in the forest," he stammered. "It's been terrorizing the town, attacking animals and even people."\n\nAnya's heart sank. The town of Willow Creek was small and peaceful, and the thought of a monster brought a shiver down her spine. She knew she had to do something to protect her family and friends.\n\nWithout a moment's hesitation, Anya opened her backpack and retrieved the shimmering sword. With a determined gleam in her eye, she turned to her terrified peers. "Don't worry," she said, her voice steady. "I'll take care of it."\n\nWith Samuel close behind her, Anya ventured into the shadowy depths of the forest. The trees seemed to whisper secrets as she passed, and the undergrowth rustled with unseen creatures. As they walked deeper into the forest, the air grew heavy and the ground beneath their feet trembled.\n\nSuddenly, they came to a clearing, and there before their eyes was the monster - a massive beast with sharp teeth, glowing red eyes, and claws that could crush a human with ease. The creature roared, a thunderous sound that shook the forest to its core.\n\nFear surged through Anya, but she refused to let it consume her. She drew the sword from its sheath and charged towards the monster. The blade shimmered in the sunlight, and as it struck the beast's hide, a blinding light erupted, enveloping everything in its radiance.\n\nWhen the light faded, the monster was gone, and in its place was a pile of shattered crystals. Anya had defeated the creature with the magic of her backpack, proving that even the smallest of objects could hold the greatest of powers.\n\nAs she and Samuel returned to the town, they were greeted as heroes. The people of Willow Creek rejoiced, and the legend of Anya, the girl with the magic backpack, was passed down through generations. And so, Anya continued her adventures, using the backpack's wonders to make the world a better place, one magical step at a time."""
to_markdown(story)
Na pitoresca cidade de Willow Creek, situada entre colinas e salgueiros sussurrando, vivia uma menina chamada Anya. Ao sair da porta de madeira estalando do chalé modesto dela, o coração dela pulou de batida com empolgação e expectativa. Hoje foi o primeiro dia de aula dela e ela mal podia esperar para mostrar seu bem premiado: uma mochila mágica.
Entregada a ela pela avó, a mochila não era uma mochila comum. Seu tecido macio verde-esmeralda brilhava com um brilho etéreo, e as tiras de couro guardavam segredos que só Anya sabia. Dentro do interior espaçoso, tinha um mundo encantado, cheio de maravilhas que despertariam a imaginação dela e mudariam a vida dela para sempre.
Os pais de Anya, a gentil Elise e Edward, o sábio, despedem-se com abraços calorosos. "Lembre-se, minha querida", sussurrou a mãe dela, "use sua magia com sabedoria e para o bem". O pai dela acrescentou: "Sempre busque conhecimento e deixe a mochila ser sua companheira de confiança."
Com um salto em seus passos, Anya foi em direção à única escola da cidade. No caminho, ela conheceu seu melhor amigo, Samuel, um menino curioso e aventureiro, com um sorriso travesso. "Oi, Anya", ele falou. "Posso ver sua mochila?"
Anya hesitou por um momento antes de abrir a aba e revelar seu conteúdo. Os olhos de Samuel se arregalaram de surpresa enquanto ele espiou por dentro. Ali, aninhados entre lápis e cadernos, havia uma espada brilhando, um livro de feitiços antigos, uma pequena bússola que sempre apontava para o norte e uma chave mágica que podia abrir qualquer fechadura.
Juntos, eles ficaram maravilhosos com as maravilhas da mochila e prometeram proteger os segredos. Ao se aproximarem da escola, Anya notou um grupo de crianças mais velhas reunidas, seus rostos gravados de medo. Curiosidade para conseguir a melhor resposta dela, ela se aproximou com cautela.
"O que há de errado?", ela perguntou.
Um menino alto e esguio deu um passo para frente. "Tem um monstro na floresta", ele gagueja. "Está aterrorizando a cidade, atacando animais e até pessoas."
O coração de Anya afundou. A cidade de Willow Creek era pequena e pacífica, e a ideia de um monstro trouxe um arrepio pela espinha. Ela sabia que tinha que fazer algo para proteger sua família e seus amigos.
Sem hesitação por um momento, Anya abriu sua mochila e pegou a espada brilhante. Com um brilho determinado nos olhos, ela se virou para os colegas aterrorizados. "Não se preocupe", ela disse, com a voz firme. "Eu vou cuidar disso."
Com Samuel atrás dela, Anya se aventurou nas profundezas sombrias da floresta. As árvores pareciam sussurrar segredos enquanto ela passava, e a vegetação sacudia com criaturas invisíveis. Conforme eles caminhavam mais profundamente na floresta, o ar ficava pesado e o chão debaixo dos pés deles tremia.
De repente, eles chegaram a uma clareira e, diante de seus olhos, havia um monstro, uma fera enorme com dentes afiados, olhos vermelhos brilhantes e garras que podiam esmagar um humano com facilidade. A criatura rugiu, um som de trovão que balançou a floresta.
O medo tomou conta de Anya, mas ela se recusou a deixar que isso a consumisse. Ela puxou a espada da bainha e avançou em direção ao monstro. A lâmina brilhava sob a luz do sol e, quando ela bateu na pele da fera, uma luz cegante irrompeu, envolvendo tudo em seu brilho.
Quando a luz diminuiu, o monstro foi embora, e no lugar dele havia uma pilha de cristais estilhaçados. Anya havia derrotado a criatura com a magia da sua mochila, provando que mesmo o menor dos objetos poderia conter os maiores poderes.
Quando ela e Samuel voltaram para a cidade, eles foram recebidos como heróis. As pessoas de Willow Creek ficaram felizes, e a lenda de Anya, a garota da mochila mágica, foi transmitida a gerações. E assim, Anya continuou suas aventuras, usando as maravilhas da mochila para tornar o mundo um lugar melhor, um passo mágico por vez.
Como usar a linguagem natural
Modelos de linguagem grandes são ferramentas multitarefa poderosas. Muitas vezes, basta pedir o que você quer ao Gemini, e ele já funciona.
A API Gemini não tem um modo JSON. Há alguns fatores que você deve considerar ao gerar estruturas de dados dessa forma:
- Às vezes, a análise falha.
- O esquema não pode ser aplicado de forma rigorosa.
Você resolverá esses problemas na próxima seção. Primeiro, teste um comando simples de linguagem natural com o esquema escrito como texto. Isso não foi otimizado:
model = model = model = genai.GenerativeModel(
model_name='models/gemini-1.5-pro-latest')
response = model.generate_content(
textwrap.dedent("""\
Please return JSON describing the the people, places, things and relationships from this story using the following schema:
{"people": list[PERSON], "places":list[PLACE], "things":list[THING], "relationships": list[RELATIONSHIP]}
PERSON = {"name": str, "description": str, "start_place_name": str, "end_place_name": str}
PLACE = {"name": str, "description": str}
THING = {"name": str, "description": str, "start_place_name": str, "end_place_name": str}
RELATIONSHIP = {"person_1_name": str, "person_2_name": str, "relationship": str}
All fields are required.
Important: Only return a single piece of valid JSON text.
Here is the story:
""") + story,
generation_config={'response_mime_type':'application/json'}
)
response.text
'{"people": [\n {\n "name": "Anya",\n "description": "A young girl who lives in the town of Willow Creek with her parents, Elise and Edward. She possesses a magical backpack that was handed down to her from her grandmother.",\n "start_place_name": "Willow Creek",\n "end_place_name": "Willow Creek"\n },\n {\n "name": "Elise",\n "description": "Anya\'s kind-hearted mother",\n "start_place_name": "Willow Creek",\n "end_place_name": "Willow Creek"\n },\n {\n "name": "Edward",\n "description": "Anya\'s wise-bearded father",\n "start_place_name": "Willow Creek",\n "end_place_name": "Willow Creek"\n },\n {\n "name": "Samuel",\n "description": "Anya\'s best friend, a curious and adventurous boy with a mischievous grin.",\n "start_place_name": "Willow Creek",\n "end_place_name": "Willow Creek"\n },\n {\n "name": "Monster",\n "description": "A massive beast with sharp teeth, glowing red eyes, and claws that could crush a human with ease.",\n "start_place_name": "Forest",\n "end_place_name": "Forest"\n }\n], "places": [\n {\n "name": "Willow Creek",\n "description": "A quaint town nestled amidst rolling hills and whispering willows."\n },\n {\n "name": "Forest",\n "description": "A shadowy place with rustling undergrowth and whispering trees."\n },\n {\n "name": "Schoolhouse",\n "description": "The only school in the town of Willow Creek."\n },\n {\n "name": "Anya\'s home",\n "description": "A modest cottage with a creaky wooden door."\n }\n], "things": [\n {\n "name": "Magic backpack",\n "description": "A magical backpack that was handed down to Anya from her grandmother. Its soft, emerald-green fabric shimmered with an ethereal glow, and its leather straps held secrets that only Anya knew.",\n "start_place_name": "Anya\'s home",\n "end_place_name": "Forest"\n },\n {\n "name": "Shimmering sword",\n "description": "A sword that shimmered in the sunlight and could strike with blinding light.",\n "start_place_name": "Magic backpack",\n "end_place_name": "Forest"\n },\n {\n "name": "Book of ancient spells",\n "description": "A book that contained ancient spells.",\n "start_place_name": "Magic backpack",\n "end_place_name": "Forest"\n },\n {\n "name": "Tiny compass",\n "description": "A compass that always pointed north.",\n "start_place_name": "Magic backpack",\n "end_place_name": "Forest"\n },\n {\n "name": "Magical key",\n "description": "A key that could open any lock.",\n "start_place_name": "Magic backpack",\n "end_place_name": "Forest"\n },\n {\n "name": "Shattered crystals",\n "description": "The remains of the monster after it was defeated by Anya\'s magic backpack.",\n "start_place_name": "Forest",\n "end_place_name": "Forest"\n }\n], "relationships": [\n {\n "person_1_name": "Anya",\n "person_2_name": "Elise",\n "relationship": "mother-daughter"\n },\n {\n "person_1_name": "Anya",\n "person_2_name": "Edward",\n "relationship": "father-daughter"\n },\n {\n "person_1_name": "Anya",\n "person_2_name": "Samuel",\n "relationship": "best friends"\n }\n]}'
Isso retornou uma string json. Tente analisá-lo:
import json
print(json.dumps(json.loads(response.text), indent=4))
{
"people": [
{
"name": "Anya",
"description": "A young girl who lives in the town of Willow Creek with her parents, Elise and Edward. She possesses a magical backpack that was handed down to her from her grandmother.",
"start_place_name": "Willow Creek",
"end_place_name": "Willow Creek"
},
{
"name": "Elise",
"description": "Anya's kind-hearted mother",
"start_place_name": "Willow Creek",
"end_place_name": "Willow Creek"
},
{
"name": "Edward",
"description": "Anya's wise-bearded father",
"start_place_name": "Willow Creek",
"end_place_name": "Willow Creek"
},
{
"name": "Samuel",
"description": "Anya's best friend, a curious and adventurous boy with a mischievous grin.",
"start_place_name": "Willow Creek",
"end_place_name": "Willow Creek"
},
{
"name": "Monster",
"description": "A massive beast with sharp teeth, glowing red eyes, and claws that could crush a human with ease.",
"start_place_name": "Forest",
"end_place_name": "Forest"
}
],
"places": [
{
"name": "Willow Creek",
"description": "A quaint town nestled amidst rolling hills and whispering willows."
},
{
"name": "Forest",
"description": "A shadowy place with rustling undergrowth and whispering trees."
},
{
"name": "Schoolhouse",
"description": "The only school in the town of Willow Creek."
},
{
"name": "Anya's home",
"description": "A modest cottage with a creaky wooden door."
}
],
"things": [
{
"name": "Magic backpack",
"description": "A magical backpack that was handed down to Anya from her grandmother. Its soft, emerald-green fabric shimmered with an ethereal glow, and its leather straps held secrets that only Anya knew.",
"start_place_name": "Anya's home",
"end_place_name": "Forest"
},
{
"name": "Shimmering sword",
"description": "A sword that shimmered in the sunlight and could strike with blinding light.",
"start_place_name": "Magic backpack",
"end_place_name": "Forest"
},
{
"name": "Book of ancient spells",
"description": "A book that contained ancient spells.",
"start_place_name": "Magic backpack",
"end_place_name": "Forest"
},
{
"name": "Tiny compass",
"description": "A compass that always pointed north.",
"start_place_name": "Magic backpack",
"end_place_name": "Forest"
},
{
"name": "Magical key",
"description": "A key that could open any lock.",
"start_place_name": "Magic backpack",
"end_place_name": "Forest"
},
{
"name": "Shattered crystals",
"description": "The remains of the monster after it was defeated by Anya's magic backpack.",
"start_place_name": "Forest",
"end_place_name": "Forest"
}
],
"relationships": [
{
"person_1_name": "Anya",
"person_2_name": "Elise",
"relationship": "mother-daughter"
},
{
"person_1_name": "Anya",
"person_2_name": "Edward",
"relationship": "father-daughter"
},
{
"person_1_name": "Anya",
"person_2_name": "Samuel",
"relationship": "best friends"
}
]
}
Isso é relativamente simples e costuma funcionar, mas é possível tornar isso mais rígido/robusto definindo o esquema usando o recurso de chamada de função da API.
Usar a chamada de função
Se você ainda não concluiu o tutorial Noções básicas sobre chamadas de função, faça isso primeiro.
Com a chamada de função, a função e os parâmetros dela são descritos para a API como um genai.protos.FunctionDeclaration. Em casos básicos, o SDK pode criar a
FunctionDeclaration usando a função e as anotações dela. Portanto, você precisará defini-los explicitamente por enquanto.
Definir o esquema
Comece definindo person como um objeto com os campos de string name, description, start_place_name e end_place_name.
person = genai.protos.Schema(
type = genai.protos.Type.OBJECT,
properties = {
'name': genai.protos.Schema(type=genai.protos.Type.STRING),
'description': genai.protos.Schema(type=genai.protos.Type.STRING),
'start_place_name': genai.protos.Schema(type=genai.protos.Type.STRING),
'end_place_name': genai.protos.Schema(type=genai.protos.Type.STRING)
},
required=['name', 'description', 'start_place_name', 'end_place_name']
)
Em seguida, defina as pessoas como uma ARRAY de objetos person:
people = genai.protos.Schema(
type=genai.protos.Type.ARRAY,
items=person
)
Depois, faça o mesmo para cada uma das entidades que você está tentando extrair:
place = genai.protos.Schema(
type = genai.protos.Type.OBJECT,
properties = {
'name': genai.protos.Schema(type=genai.protos.Type.STRING),
'description': genai.protos.Schema(type=genai.protos.Type.STRING),
}
)
places = genai.protos.Schema(
type=genai.protos.Type.ARRAY,
items=place
)
thing = genai.protos.Schema(
type = genai.protos.Type.OBJECT,
properties = {
'name': genai.protos.Schema(type=genai.protos.Type.STRING),
'description': genai.protos.Schema(type=genai.protos.Type.STRING),
}
)
things = genai.protos.Schema(
type=genai.protos.Type.ARRAY,
items=thing
)
relationship = genai.protos.Schema(
type = genai.protos.Type.OBJECT,
properties = {
'person_1_name': genai.protos.Schema(type=genai.protos.Type.STRING),
'person_2_name': genai.protos.Schema(type=genai.protos.Type.STRING),
'relationship': genai.protos.Schema(type=genai.protos.Type.STRING),
}
)
relationships = genai.protos.Schema(
type=genai.protos.Type.ARRAY,
items=relationship
)
Agora crie a FunctionDeclaration:
add_to_database = genai.protos.FunctionDeclaration(
name="add_to_database",
description=textwrap.dedent("""\
Adds entities to the database.
"""),
parameters=genai.protos.Schema(
type=genai.protos.Type.OBJECT,
properties = {
'people': people,
'places': places,
'things': things,
'relationships': relationships
}
)
)
Chamar a API
Como você viu em Noções básicas sobre chamada de função, agora é possível transmitir esse FunctionDeclaration ao argumento tools do construtor genai.GenerativeModel. O construtor também aceita uma representação JSON equivalente da declaração da função:
model = model = genai.GenerativeModel(
model_name='models/gemini-1.5-pro-latest',
tools = [add_to_database])
Toda vez que você chamar a API, o SDK vai enviar as ferramentas com seu comando, e o modelo vai chamar essa função definida:
result = model.generate_content(f"""
Please add the people, places, things, and relationships from this story to the database:
{story}
""",
# Force a function call
tool_config={'function_calling_config':'ANY'})
Agora não há texto para analisar. O resultado é uma estrutura de dados.
'text' in result.candidates[0].content.parts[0]
False
'function_call' in result.candidates[0].content.parts[0]
True
fc = result.candidates[0].content.parts[0].function_call
print(type(fc))
<class 'google.ai.generativelanguage_v1beta.types.content.FunctionCall'>
A classe genai.protos.FunctionCall é baseada nos buffers de protocolo do Google.
Converta-a em um objeto compatível com JSON mais conhecido:
print(json.dumps(type(fc).to_dict(fc), indent=4))
{
"name": "add_to_database",
"args": {
"things": [
{
"name": "Magical Backpack",
"description": "Anya's prized possession, the Magical Backpack, is no ordinary satchel. Its soft, emerald-green fabric shimmers with an ethereal glow, and its leather straps have secrets that only Anya knows. Within its capacious interior lay an enchanted world, filled with wonders that would ignite her imagination and change her life forever."
},
{
"name": "Shimmering Sword",
"description": "Among the wonders in Anya's Magical Backpack, lies a shimmering sword. With a determined gleam in her eye, she retrieved the shimmering sword and charged towards the monster."
},
{
"description": "Residing within the Magical Backpack, the Book of Ancient Spells holds secrets untold.",
"name": "Book of Ancient Spells"
},
{
"description": "Tucked away in the Magical Backpack is a tiny compass that always points north.",
"name": "Tiny Compass that Always Points North"
},
{
"description": "Hidden within the Magical Backpack is a magical key that can open any lock.",
"name": "Magical Key that Can Open Any Lock"
}
],
"relationships": [
{
"relationship": "Mother-Daughter",
"person_1_name": "Anya",
"person_2_name": "Elise"
},
{
"person_2_name": "Edward",
"relationship": "Father-Daughter",
"person_1_name": "Anya"
},
{
"person_2_name": "Samuel",
"person_1_name": "Anya",
"relationship": "Best Friends"
}
],
"people": [
{
"name": "Anya",
"description": "Anya, the main character of the story, is a young girl with a magical backpack.",
"start_place_name": "Willow Creek",
"end_place_name": "Unknown"
},
{
"name": "Elise",
"description": "Anya's mother, Elise is a kind-hearted woman.",
"end_place_name": "Unknown",
"start_place_name": "Willow Creek"
},
{
"start_place_name": "Willow Creek",
"end_place_name": "Unknown",
"name": "Edward",
"description": "Anya's father, Edward is a wise-bearded man."
},
{
"end_place_name": "Unknown",
"start_place_name": "Willow Creek",
"description": "Anya's best friend, Samuel is a curious and adventurous boy with a mischievous grin.",
"name": "Samuel"
}
],
"places": [
{
"description": "The quaint town of Willow Creek is nestled amidst rolling hills and whispering willows.",
"name": "Willow Creek"
},
{
"description": "The town's only schoolhouse.",
"name": "Schoolhouse"
},
{
"description": "A shadowy place filled with secrets and dangers, the Forest is home to a terrifying monster.",
"name": "Forest"
}
]
}
}
Conclusão
Embora a API possa lidar com problemas de extração de dados estruturados com entrada e saída de texto puro, o uso da chamada de função é provavelmente mais confiável, porque permite definir um esquema restrito e elimina uma etapa de análise potencialmente propensa a erros.