diff --git a/docs/asciidoc/modules/ROOT/nav.adoc b/docs/asciidoc/modules/ROOT/nav.adoc index 0dbcda02c4..ed04ea5040 100644 --- a/docs/asciidoc/modules/ROOT/nav.adoc +++ b/docs/asciidoc/modules/ROOT/nav.adoc @@ -68,6 +68,8 @@ include::partial$generated-documentation/nav.adoc[] ** xref:ml/bedrock.adoc[] ** xref:ml/watsonai.adoc[] ** xref:ml/mixedbread.adoc[] + ** xref:ml/genai.adoc[] + ** xref:ml/rag.adoc[] * xref:background-operations/index.adoc[] ** xref::background-operations/apoc-load-directory-async.adoc[] diff --git a/docs/asciidoc/modules/ROOT/pages/ml/genai.adoc b/docs/asciidoc/modules/ROOT/pages/ml/genai.adoc new file mode 100644 index 0000000000..9d35b29752 --- /dev/null +++ b/docs/asciidoc/modules/ROOT/pages/ml/genai.adoc @@ -0,0 +1,342 @@ +[[genai-assistant]] += GenAI Assistant Procedures +:description: This section describes procedures that can be used to access the GenAI Assistant. + +== Query with natural language + +This procedure `apoc.ml.query` takes a question in natural language and returns the results of that query. + +It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. + +.Query call +[source,cypher] +---- +CALL apoc.ml.query("What movies did Tom Hanks play in?") yield value, query +RETURN * +---- + +.Example response +[source, bash] +---- ++------------------------------------------------------------------------------------------------------------------------------+ +| value | query | ++------------------------------------------------------------------------------------------------------------------------------+ +| {m.title -> "You've Got Mail"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "Apollo 13"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "Joe Versus the Volcano"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "That Thing You Do"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "Cloud Atlas"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "The Da Vinci Code"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "Sleepless in Seattle"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "A League of Their Own"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "The Green Mile"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "Charlie Wilson's War"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "Cast Away"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | +| {m.title -> "The Polar Express"} | "cypher +MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) +RETURN m.title +" | ++------------------------------------------------------------------------------------------------------------------------------+ +12 rows +---- + +.Input Parameters +[%autowidth, opts=header] +|=== +| name | description +| question | The question in the natural language +| conf | An optional configuration map, please check the next section | no +|=== + +.Configuration map +[%autowidth, opts=header] +|=== +| name | description | mandatory +| retries | The number of retries in case of API call failures | no, default `3` +| retryWithError | If true, in case of error retry the api adding the following messages to the body request: +{`"role":"user", "content": "The previous Cypher Statement throws the following error, consider it to return the correct statement: ``"}, {"role":"assistant", "content":"Cypher Statement (in backticks):"}` | no, default `false` +| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined +| model | The Open AI model | no, default `gpt-3.5-turbo` +| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number +|=== + +.Results +[%autowidth, opts=header] +|=== +| name | description +| value | the result of the query +| cypher | the query used to compute the result +|=== + + +== Describe the graph model with natural language + +This procedure `apoc.ml.schema` returns a description, in natural language, of the underlying dataset. + +It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. + +.Query call +[source,cypher] +---- +CALL apoc.ml.schema() yield value +RETURN * +---- + +.Example response +[source, bash] +---- ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| value | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "The graph database schema represents a system where users can follow other users and review movies. Users (:Person) can either follow other users (:Person) or review movies (:Movie). The relationships allow users to express their preferences and opinions about movies. This schema can be compared to social media platforms where users can follow each other and leave reviews or ratings for movies they have watched. It can also be related to movie recommendation systems where user preferences and reviews play a crucial role in generating personalized recommendations." | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row +---- + +.Input Parameters +[%autowidth, opts=header] +|=== +| name | description +| conf | An optional configuration map, please check the next section +|=== + +.Configuration map +[%autowidth, opts=header] +|=== +| name | description | mandatory +| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined +| model | The Open AI model | no, default `gpt-3.5-turbo` +| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number +|=== + +.Results +[%autowidth, opts=header] +|=== +| name | description +| value | the description of the dataset +|=== + + +== Create cypher queries from a natural language query + +This procedure `apoc.ml.cypher` takes a natural language question and transforms it into a number of requested cypher queries. + +It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. + +.Query call +[source,cypher] +---- +CALL apoc.ml.cypher("Who are the actors which also directed a movie?", {count: 4}) yield cypher +RETURN * +---- + +.Example response +[source, bash] +---- ++----------------------------------------------------------------------------------------------------------------+ +| query | ++----------------------------------------------------------------------------------------------------------------+ +| " +MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(d:Person) +RETURN a.name as actor, d.name as director +" | +| "cypher +MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(a) +RETURN a.name +" | +| " +MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(d:Person) +RETURN a.name +" | +| "cypher +MATCH (a:Person)-[:ACTED_IN]->(:Movie)<-[:DIRECTED]-(a) +RETURN DISTINCT a.name +" | ++----------------------------------------------------------------------------------------------------------------+ +4 rows +---- + +.Input Parameters +[%autowidth, opts=header] +|=== +| name | description | mandatory +| question | The question in the natural language | yes +| conf | An optional configuration map, please check the next section | no +|=== + +.Configuration map +[%autowidth, opts=header] +|=== +| name | description | mandatory +| count | The number of queries to retrieve | no, default `1` +| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined +| model | The Open AI model | no, default `gpt-3.5-turbo` +| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number +|=== + +.Results +[%autowidth, opts=header] +|=== +| name | description +| value | the description of the dataset +|=== + +== Create a natural language query explanation from a cypher query + +This procedure `apoc.ml.fromCypher` takes a natural language question and transforms it into natural language query explanation. + +It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. + +.Query call +[source,cypher] +---- +CALL apoc.ml.cypher("MATCH (p:Person {name: "Tom Hanks"})-[:ACTED_IN]->(m:Movie) RETURN m", {}) yield value +RETURN * +---- + +.Example response +[opts="header"] +|=== +| value +| this database schema represents a simplified version of a common movie database model. the `movie` node represents a movie entity with attributes such as the year it was released, a tagline, and the movie title. the `person` node represents a person involved in the movie industry, with attributes for the person's year of birth and name. the relationship `directed` connects a `person` node to a `movie` node, indicating that the person directed the movie. +in terms of domains, this schema can be related to the entertainment industry, specifically the movie industry. movies and people involved in creating those movies are fundamental entities in this domain. the `directed` relationship captures the directed-by relationship between a person and a movie. this type of model can be extended to include other relationships like `acted_in`, `produced`, `wrote`, etc., to capture more complex connections within the movie industry. +overall, this graph database schema provides a simple yet powerful representation of entities and relationships in the movie domain, allowing for querying and analysis of connections within the industry. +|=== + +.Input Parameters +[%autowidth, opts=header] +|=== +| name | description | mandatory +| cypher | The question in the natural language | yes +| conf | An optional configuration map, please check the next section | no +|=== + +.Configuration map +[%autowidth, opts=header] +|=== +| name | description | mandatory +| retries | The number of retries in case of API call failures | no, default `3` +| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined +| model | The Open AI model | no, default `gpt-3.5-turbo` +| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number +|=== + + +.Results +[%autowidth, opts=header] +|=== +| name | description +| value | the description of the dataset +|=== + + +== Create explanation of the subgraph from a set of queries + +This procedure `apoc.ml.fromQueries` returns an explanation, in natural language, of the given set of queries. + +It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. + +.Query call +[source,cypher] +---- +CALL apoc.ml.fromQueries(['MATCH (n:Movie) RETURN n', 'MATCH (n:Person) RETURN n'], + {apiKey: }) +YIELD value +RETURN * +---- + +.Example response +[source, bash] +---- ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| value | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "The database represents movies and people, like in a movie database or social network. + There are no defined relationships between nodes, allowing flexibility for future connections. + The Movie node includes properties like title, tagline, and release year." | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row +---- + +.Query call with path +[source,cypher] +---- +CALL apoc.ml.fromQueries(['MATCH (n:Movie) RETURN n', 'MATCH p=(n:Movie)--() RETURN p'], + {apiKey: }) +YIELD value +RETURN * +---- + +.Example response +[source, bash] +---- ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| value | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| "models relationships in the movie industry, connecting :Person nodes to :Movie nodes. + It represents actors, directors, writers, producers, and reviewers connected to movies they are involved with. + Similar to a social network graph but specialized for the entertainment industry. + Each relationship type corresponds to common roles in movie production and reviewing. + Allows for querying and analyzing connections and collaborations within the movie business." | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row +---- + + +.Input Parameters +[%autowidth, opts=header] +|=== +| name | description +| queries | The list of queries +| conf | An optional configuration map, please check the next section +|=== + +.Configuration map +[%autowidth, opts=header] +|=== +| name | description | mandatory +| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined +| model | The Open AI model | no, default `gpt-3.5-turbo` +| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number +|=== + +.Results +[%autowidth, opts=header] +|=== +| name | description +| value | the description of the dataset +|=== + diff --git a/docs/asciidoc/modules/ROOT/pages/ml/index.adoc b/docs/asciidoc/modules/ROOT/pages/ml/index.adoc index dfb9c88570..b5271a496b 100644 --- a/docs/asciidoc/modules/ROOT/pages/ml/index.adoc +++ b/docs/asciidoc/modules/ROOT/pages/ml/index.adoc @@ -12,3 +12,5 @@ This section includes: * xref::ml/bedrock.adoc[] * xref::ml/watsonai.adoc[] * xref::ml/mixedbread.adoc[] +* xref::ml/genai.adoc[] +* xref::ml/rag.adoc[] diff --git a/docs/asciidoc/modules/ROOT/pages/ml/openai.adoc b/docs/asciidoc/modules/ROOT/pages/ml/openai.adoc index b31783d678..12f27057a9 100644 --- a/docs/asciidoc/modules/ROOT/pages/ml/openai.adoc +++ b/docs/asciidoc/modules/ROOT/pages/ml/openai.adoc @@ -249,532 +249,3 @@ CALL apoc.ml.openai.chat([{"role": "user", "content": "Explain the importance of '', {endpoint: 'https://api.groq.com/openai/v1', model: 'mixtral-8x7b-32768'}) ---- - - - -== Query with natural language - -This procedure `apoc.ml.query` takes a question in natural language and returns the results of that query. - -It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. - -.Query call -[source,cypher] ----- -CALL apoc.ml.query("What movies did Tom Hanks play in?") yield value, query -RETURN * ----- - -.Example response -[source, bash] ----- -+------------------------------------------------------------------------------------------------------------------------------+ -| value | query | -+------------------------------------------------------------------------------------------------------------------------------+ -| {m.title -> "You've Got Mail"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "Apollo 13"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "Joe Versus the Volcano"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "That Thing You Do"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "Cloud Atlas"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "The Da Vinci Code"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "Sleepless in Seattle"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "A League of Their Own"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "The Green Mile"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "Charlie Wilson's War"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "Cast Away"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -| {m.title -> "The Polar Express"} | "cypher -MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'}) -RETURN m.title -" | -+------------------------------------------------------------------------------------------------------------------------------+ -12 rows ----- - -.Input Parameters -[%autowidth, opts=header] -|=== -| name | description -| question | The question in the natural language -| conf | An optional configuration map, please check the next section | no -|=== - -.Configuration map -[%autowidth, opts=header] -|=== -| name | description | mandatory -| retries | The number of retries in case of API call failures | no, default `3` -| retryWithError | If true, in case of error retry the api adding the following messages to the body request: -{`"role":"user", "content": "The previous Cypher Statement throws the following error, consider it to return the correct statement: ``"}, {"role":"assistant", "content":"Cypher Statement (in backticks):"}` | no, default `false` -| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined -| model | The Open AI model | no, default `gpt-3.5-turbo` -| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number -|=== - -.Results -[%autowidth, opts=header] -|=== -| name | description -| value | the result of the query -| cypher | the query used to compute the result -|=== - - -== Describe the graph model with natural language - -This procedure `apoc.ml.schema` returns a description, in natural language, of the underlying dataset. - -It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. - -.Query call -[source,cypher] ----- -CALL apoc.ml.schema() yield value -RETURN * ----- - -.Example response -[source, bash] ----- -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| value | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| "The graph database schema represents a system where users can follow other users and review movies. Users (:Person) can either follow other users (:Person) or review movies (:Movie). The relationships allow users to express their preferences and opinions about movies. This schema can be compared to social media platforms where users can follow each other and leave reviews or ratings for movies they have watched. It can also be related to movie recommendation systems where user preferences and reviews play a crucial role in generating personalized recommendations." | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row ----- - -.Input Parameters -[%autowidth, opts=header] -|=== -| name | description -| conf | An optional configuration map, please check the next section -|=== - -.Configuration map -[%autowidth, opts=header] -|=== -| name | description | mandatory -| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined -| model | The Open AI model | no, default `gpt-3.5-turbo` -| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number -|=== - -.Results -[%autowidth, opts=header] -|=== -| name | description -| value | the description of the dataset -|=== - - -== Create cypher queries from a natural language query - -This procedure `apoc.ml.cypher` takes a natural language question and transforms it into a number of requested cypher queries. - -It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. - -.Query call -[source,cypher] ----- -CALL apoc.ml.cypher("Who are the actors which also directed a movie?", {count: 4}) yield cypher -RETURN * ----- - -.Example response -[source, bash] ----- -+----------------------------------------------------------------------------------------------------------------+ -| query | -+----------------------------------------------------------------------------------------------------------------+ -| " -MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(d:Person) -RETURN a.name as actor, d.name as director -" | -| "cypher -MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(a) -RETURN a.name -" | -| " -MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(d:Person) -RETURN a.name -" | -| "cypher -MATCH (a:Person)-[:ACTED_IN]->(:Movie)<-[:DIRECTED]-(a) -RETURN DISTINCT a.name -" | -+----------------------------------------------------------------------------------------------------------------+ -4 rows ----- - -.Input Parameters -[%autowidth, opts=header] -|=== -| name | description | mandatory -| question | The question in the natural language | yes -| conf | An optional configuration map, please check the next section | no -|=== - -.Configuration map -[%autowidth, opts=header] -|=== -| name | description | mandatory -| count | The number of queries to retrieve | no, default `1` -| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined -| model | The Open AI model | no, default `gpt-3.5-turbo` -| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number -|=== - -.Results -[%autowidth, opts=header] -|=== -| name | description -| value | the description of the dataset -|=== - -== Create a natural language query explanation from a cypher query - -This procedure `apoc.ml.fromCypher` takes a natural language question and transforms it into natural language query explanation. - -It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. - -.Query call -[source,cypher] ----- -CALL apoc.ml.cypher("MATCH (p:Person {name: "Tom Hanks"})-[:ACTED_IN]->(m:Movie) RETURN m", {}) yield value -RETURN * ----- - -.Example response -[opts="header"] -|=== -| value -| this database schema represents a simplified version of a common movie database model. the `movie` node represents a movie entity with attributes such as the year it was released, a tagline, and the movie title. the `person` node represents a person involved in the movie industry, with attributes for the person's year of birth and name. the relationship `directed` connects a `person` node to a `movie` node, indicating that the person directed the movie. -in terms of domains, this schema can be related to the entertainment industry, specifically the movie industry. movies and people involved in creating those movies are fundamental entities in this domain. the `directed` relationship captures the directed-by relationship between a person and a movie. this type of model can be extended to include other relationships like `acted_in`, `produced`, `wrote`, etc., to capture more complex connections within the movie industry. -overall, this graph database schema provides a simple yet powerful representation of entities and relationships in the movie domain, allowing for querying and analysis of connections within the industry. -|=== - -.Input Parameters -[%autowidth, opts=header] -|=== -| name | description | mandatory -| cypher | The question in the natural language | yes -| conf | An optional configuration map, please check the next section | no -|=== - -.Configuration map -[%autowidth, opts=header] -|=== -| name | description | mandatory -| retries | The number of retries in case of API call failures | no, default `3` -| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined -| model | The Open AI model | no, default `gpt-3.5-turbo` -| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number -|=== - - -.Results -[%autowidth, opts=header] -|=== -| name | description -| value | the description of the dataset -|=== - - -== Create explanation of the subgraph from a set of queries - -This procedure `apoc.ml.fromQueries` returns an explanation, in natural language, of the given set of queries. - -It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. - -.Query call -[source,cypher] ----- -CALL apoc.ml.fromQueries(['MATCH (n:Movie) RETURN n', 'MATCH (n:Person) RETURN n'], - {apiKey: }) -YIELD value -RETURN * ----- - -.Example response -[source, bash] ----- -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| value | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| "The database represents movies and people, like in a movie database or social network. - There are no defined relationships between nodes, allowing flexibility for future connections. - The Movie node includes properties like title, tagline, and release year." | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row ----- - -.Query call with path -[source,cypher] ----- -CALL apoc.ml.fromQueries(['MATCH (n:Movie) RETURN n', 'MATCH p=(n:Movie)--() RETURN p'], - {apiKey: }) -YIELD value -RETURN * ----- - -.Example response -[source, bash] ----- -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| value | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| "models relationships in the movie industry, connecting :Person nodes to :Movie nodes. - It represents actors, directors, writers, producers, and reviewers connected to movies they are involved with. - Similar to a social network graph but specialized for the entertainment industry. - Each relationship type corresponds to common roles in movie production and reviewing. - Allows for querying and analyzing connections and collaborations within the movie business." | -+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row ----- - - -.Input Parameters -[%autowidth, opts=header] -|=== -| name | description -| queries | The list of queries -| conf | An optional configuration map, please check the next section -|=== - -.Configuration map -[%autowidth, opts=header] -|=== -| name | description | mandatory -| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined -| model | The Open AI model | no, default `gpt-3.5-turbo` -| sample | The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It's used as a parameter to `apoc.meta.data` procedure that computes the schema | no, default is a random number -|=== - -.Results -[%autowidth, opts=header] -|=== -| name | description -| value | the description of the dataset -|=== - -== Query with Retrieval-augmented generation (RAG) technique - -This procedure `apoc.ml.rag` takes a list of paths or a vector index name, relevant attributes and a natural language question -to create a prompt implementing a Retrieval-augmented generation (RAG) technique. - -See https://aws.amazon.com/what-is/retrieval-augmented-generation/[here] for more info about the RAG process. - -It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. - - - -.Input Parameters -[%autowidth, opts=header] -|=== -| name | description | mandatory -| paths | the list of paths to retrieve and augment the prompt, it can also be a matching query or a vector index name | yes -| attributes | the relevant attributes useful to retrieve and augment the prompt | yes -| question | the user question | yes -| conf | An optional configuration map, please check the next section | no -|=== - - -.Configuration map -[%autowidth, opts=header] -|=== -| name | description | mandatory -| getLabelTypes | add the label / rel-type names to the info to augment the prompt | no, default `true` -| embeddings | to search similar embeddings stored into a node vector index (in case of `embeddings: "NODE"`) or relationship vector index (in case of `embeddings: "REL"`) | no, default `"FALSE"` -| topK | number of neighbors to find for each node (in case of `embeddings: "NODE"`) or relationships (in case of `embeddings: "REL"`) | no, default `40` -| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined -| prompt | the base prompt to be augmented with the context | no, default is: - -"You are a customer service agent that helps a customer with answering questions about a service. -Use the following context to answer the `user question` at the end. -Make sure not to make any changes to the context if possible when prepare answers to provide accurate responses. -If you don't know the answer, just say \`Sorry, I don't know`, don't try to make up an answer." -|=== - - -Using the apoc.ml.rag procedure we can reduce AI hallucinations (i.e. false or misleading responses), -providing relevant and up-to-date information to our procedure via the 1st parameter. - -For example, by executing the following procedure (with the `gpt-3.5-turbo` model, last updated in January 2022) -we have a hallucination - -.Query call -[source,cypher] ----- -CALL apoc.ml.openai.chat([ - {role:"user", content: "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?"} -], $apiKey) ----- - -.Example response -[opts="header"] -|=== -| value -| The gold medal in curling at the 2022 Winter Olympics was won by the Swedish men's team and the Russian women's team. -|=== - -So, we can use the RAG technique to provide real results. -For example with the given dataset (with data taken from https://en.wikipedia.org/wiki/Curling_at_the_2022_Winter_Olympics[this wikipedia page]): - -.wikipedia dataset -[source,cypher] ----- -CREATE (mixed2022:Discipline {title:"Mixed doubles's curling", year: 2022}) -WITH mixed2022 -CREATE (:Athlete {name: 'Stefania Constantini', country: 'Italy', irrelevant: 'asdasd'})-[:HAS_MEDAL {medal: 'Gold', irrelevant2: 'asdasd'}]->(mixed2022) -CREATE (:Athlete {name: 'Amos Mosaner', country: 'Italy', irrelevant: 'qweqwe'})-[:HAS_MEDAL {medal: 'Gold', irrelevant2: 'rwerew'}]->(mixed2022) -CREATE (:Athlete {name: 'Kristin Skaslien', country: 'Norway', irrelevant: 'dfgdfg'})-[:HAS_MEDAL {medal: 'Silver', irrelevant2: 'gdfg'}]->(mixed2022) -CREATE (:Athlete {name: 'Magnus Nedregotten', country: 'Norway', irrelevant: 'xcvxcv'})-[:HAS_MEDAL {medal: 'Silver', irrelevant2: 'asdasd'}]->(mixed2022) -CREATE (:Athlete {name: 'Almida de Val', country: 'Sweden', irrelevant: 'rtyrty'})-[:HAS_MEDAL {medal: 'Bronze', irrelevant2: 'bfbfb'}]->(mixed2022) -CREATE (:Athlete {name: 'Oskar Eriksson', country: 'Sweden', irrelevant: 'qwresdc'})-[:HAS_MEDAL {medal: 'Bronze', irrelevant2: 'juju'}]->(mixed2022) ----- - -we can execute: - -.Query call -[source,cypher] ----- -MATCH path=(:Athlete)-[:HAS_MEDAL]->(Discipline) -WITH collect(path) AS paths -CALL apoc.ml.rag(paths, - ["name", "country", "medal", "title", "year"], - "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?", - {apiKey: $apiKey} -) YIELD value -RETURN value ----- - -.Example response -[opts="header"] -|=== -| value -| The gold medal in curling at the 2022 Winter Olympics was won by Stefania Constantini and Amos Mosaner from Italy. -|=== - -or: - -.Query call -[source,cypher] ----- -MATCH path=(:Athlete)-[:HAS_MEDAL]->(Discipline) -WITH collect(path) AS paths -CALL apoc.ml.rag(paths, - ["name", "country", "medal", "title", "year"], - "Which athletes won the silver medal in mixed doubles's curling at the 2022 Winter Olympics?", - {apiKey: $apiKey} -) YIELD value -RETURN value ----- - -.Example response -[opts="header"] -|=== -| value -| The gold medal in curling at the 2022 Winter Olympics was won by Kristin Skaslien and Magnus Nedregotten from Norway. -|=== - -We can also pass a string query returning paths/relationships/nodes, for example: - -[source,cypher] ----- -CALL apoc.ml.rag("MATCH path=(:Athlete)-[:HAS_MEDAL]->(Discipline) WITH collect(path) AS paths", - ["name", "country", "medal", "title", "year"], - "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?", - {apiKey: $apiKey} -) YIELD value -RETURN value ----- - -.Example response -[opts="header"] -|=== -| value -| The gold medal in curling at the 2022 Winter Olympics was won by Stefania Constantini and Amos Mosaner from Italy. -|=== - -or we can pass a vector index name as the 1st parameter, in case we stored useful info into embedding nodes. -For example, given this node vector index: - -[source,cypher] ----- -CREATE VECTOR INDEX `rag-embeddings` -FOR (n:RagEmbedding) ON (n.embedding) -OPTIONS {indexConfig: { - `vector.dimensions`: 1536, - `vector.similarity_function`: 'cosine' -}} ----- - -and some (:RagEmbedding) nodes with the `text` properties, we can execute: - -[source,cypher] ----- -CALL apoc.ml.rag("rag-embeddings", - ["text"], - "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?", - {apiKey: $apiKey, embeddings: "NODE", topK: 20} -) YIELD value -RETURN value ----- - -or, with a relationship vector index: - - -[source,cypher] ----- -CREATE VECTOR INDEX `rag-rel-embeddings` -FOR ()-[r:RAG_EMBEDDING]-() ON (r.embedding) -OPTIONS {indexConfig: { - `vector.dimensions`: 1536, - `vector.similarity_function`: 'cosine' -}} ----- - -and some [:RagEmbedding] relationships with the `text` properties, we can execute: - -[source,cypher] ----- -CALL apoc.ml.rag("rag-rel-embeddings", - ["text"], - "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?", - {apiKey: $apiKey, embeddings: "REL", topK: 20} -) YIELD value -RETURN value ----- \ No newline at end of file diff --git a/docs/asciidoc/modules/ROOT/pages/ml/rag.adoc b/docs/asciidoc/modules/ROOT/pages/ml/rag.adoc new file mode 100644 index 0000000000..f4029f055a --- /dev/null +++ b/docs/asciidoc/modules/ROOT/pages/ml/rag.adoc @@ -0,0 +1,193 @@ +[[rag]] += RAG - Retrieval Augmented Generation Procedures +:description: This section describes procedures that can be used to access the RAG - Retrieval Augmented Generation. + +== Query with Retrieval-augmented generation (RAG) technique + +This procedure `apoc.ml.rag` takes a list of paths or a vector index name, relevant attributes and a natural language question +to create a prompt implementing a Retrieval-augmented generation (RAG) technique. + +See https://aws.amazon.com/what-is/retrieval-augmented-generation/[here] for more info about the RAG process. + +It uses the `chat/completions` API which is https://platform.openai.com/docs/api-reference/chat/create[documented here^]. + + + +.Input Parameters +[%autowidth, opts=header] +|=== +| name | description | mandatory +| paths | the list of paths to retrieve and augment the prompt, it can also be a matching query or a vector index name | yes +| attributes | the relevant attributes useful to retrieve and augment the prompt | yes +| question | the user question | yes +| conf | An optional configuration map, please check the next section | no +|=== + + +.Configuration map +[%autowidth, opts=header] +|=== +| name | description | mandatory +| getLabelTypes | add the label / rel-type names to the info to augment the prompt | no, default `true` +| embeddings | to search similar embeddings stored into a node vector index (in case of `embeddings: "NODE"`) or relationship vector index (in case of `embeddings: "REL"`) | no, default `"FALSE"` +| topK | number of neighbors to find for each node (in case of `embeddings: "NODE"`) or relationships (in case of `embeddings: "REL"`) | no, default `40` +| apiKey | OpenAI API key | in case `apoc.openai.key` is not defined +| prompt | the base prompt to be augmented with the context | no, default is: + +"You are a customer service agent that helps a customer with answering questions about a service. +Use the following context to answer the `user question` at the end. +Make sure not to make any changes to the context if possible when prepare answers to provide accurate responses. +If you don't know the answer, just say \`Sorry, I don't know`, don't try to make up an answer." +|=== + + +Using the apoc.ml.rag procedure we can reduce AI hallucinations (i.e. false or misleading responses), +providing relevant and up-to-date information to our procedure via the 1st parameter. + +For example, by executing the following procedure (with the `gpt-3.5-turbo` model, last updated in January 2022) +we have a hallucination + +.Query call +[source,cypher] +---- +CALL apoc.ml.openai.chat([ + {role:"user", content: "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?"} +], $apiKey) +---- + +.Example response +[opts="header"] +|=== +| value +| The gold medal in curling at the 2022 Winter Olympics was won by the Swedish men's team and the Russian women's team. +|=== + +So, we can use the RAG technique to provide real results. +For example with the given dataset (with data taken from https://en.wikipedia.org/wiki/Curling_at_the_2022_Winter_Olympics[this wikipedia page]): + +.wikipedia dataset +[source,cypher] +---- +CREATE (mixed2022:Discipline {title:"Mixed doubles's curling", year: 2022}) +WITH mixed2022 +CREATE (:Athlete {name: 'Stefania Constantini', country: 'Italy', irrelevant: 'asdasd'})-[:HAS_MEDAL {medal: 'Gold', irrelevant2: 'asdasd'}]->(mixed2022) +CREATE (:Athlete {name: 'Amos Mosaner', country: 'Italy', irrelevant: 'qweqwe'})-[:HAS_MEDAL {medal: 'Gold', irrelevant2: 'rwerew'}]->(mixed2022) +CREATE (:Athlete {name: 'Kristin Skaslien', country: 'Norway', irrelevant: 'dfgdfg'})-[:HAS_MEDAL {medal: 'Silver', irrelevant2: 'gdfg'}]->(mixed2022) +CREATE (:Athlete {name: 'Magnus Nedregotten', country: 'Norway', irrelevant: 'xcvxcv'})-[:HAS_MEDAL {medal: 'Silver', irrelevant2: 'asdasd'}]->(mixed2022) +CREATE (:Athlete {name: 'Almida de Val', country: 'Sweden', irrelevant: 'rtyrty'})-[:HAS_MEDAL {medal: 'Bronze', irrelevant2: 'bfbfb'}]->(mixed2022) +CREATE (:Athlete {name: 'Oskar Eriksson', country: 'Sweden', irrelevant: 'qwresdc'})-[:HAS_MEDAL {medal: 'Bronze', irrelevant2: 'juju'}]->(mixed2022) +---- + +we can execute: + +.Query call +[source,cypher] +---- +MATCH path=(:Athlete)-[:HAS_MEDAL]->(Discipline) +WITH collect(path) AS paths +CALL apoc.ml.rag(paths, + ["name", "country", "medal", "title", "year"], + "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?", + {apiKey: $apiKey} +) YIELD value +RETURN value +---- + +.Example response +[opts="header"] +|=== +| value +| The gold medal in curling at the 2022 Winter Olympics was won by Stefania Constantini and Amos Mosaner from Italy. +|=== + +or: + +.Query call +[source,cypher] +---- +MATCH path=(:Athlete)-[:HAS_MEDAL]->(Discipline) +WITH collect(path) AS paths +CALL apoc.ml.rag(paths, + ["name", "country", "medal", "title", "year"], + "Which athletes won the silver medal in mixed doubles's curling at the 2022 Winter Olympics?", + {apiKey: $apiKey} +) YIELD value +RETURN value +---- + +.Example response +[opts="header"] +|=== +| value +| The gold medal in curling at the 2022 Winter Olympics was won by Kristin Skaslien and Magnus Nedregotten from Norway. +|=== + +We can also pass a string query returning paths/relationships/nodes, for example: + +[source,cypher] +---- +CALL apoc.ml.rag("MATCH path=(:Athlete)-[:HAS_MEDAL]->(Discipline) WITH collect(path) AS paths", + ["name", "country", "medal", "title", "year"], + "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?", + {apiKey: $apiKey} +) YIELD value +RETURN value +---- + +.Example response +[opts="header"] +|=== +| value +| The gold medal in curling at the 2022 Winter Olympics was won by Stefania Constantini and Amos Mosaner from Italy. +|=== + +or we can pass a vector index name as the 1st parameter, in case we stored useful info into embedding nodes. +For example, given this node vector index: + +[source,cypher] +---- +CREATE VECTOR INDEX `rag-embeddings` +FOR (n:RagEmbedding) ON (n.embedding) +OPTIONS {indexConfig: { + `vector.dimensions`: 1536, + `vector.similarity_function`: 'cosine' +}} +---- + +and some (:RagEmbedding) nodes with the `text` properties, we can execute: + +[source,cypher] +---- +CALL apoc.ml.rag("rag-embeddings", + ["text"], + "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?", + {apiKey: $apiKey, embeddings: "NODE", topK: 20} +) YIELD value +RETURN value +---- + +or, with a relationship vector index: + + +[source,cypher] +---- +CREATE VECTOR INDEX `rag-rel-embeddings` +FOR ()-[r:RAG_EMBEDDING]-() ON (r.embedding) +OPTIONS {indexConfig: { + `vector.dimensions`: 1536, + `vector.similarity_function`: 'cosine' +}} +---- + +and some [:RagEmbedding] relationships with the `text` properties, we can execute: + +[source,cypher] +---- +CALL apoc.ml.rag("rag-rel-embeddings", + ["text"], + "Which athletes won the gold medal in mixed doubles's curling at the 2022 Winter Olympics?", + {apiKey: $apiKey, embeddings: "REL", topK: 20} +) YIELD value +RETURN value +---- +