http://git-wip-us.apache.org/repos/asf/predictionio-site/blob/9fe018b6/templates/complementarypurchase/quickstart/index.html ---------------------------------------------------------------------- diff --git a/templates/complementarypurchase/quickstart/index.html b/templates/complementarypurchase/quickstart/index.html index e856e0c..43eceab 100644 --- a/templates/complementarypurchase/quickstart/index.html +++ b/templates/complementarypurchase/quickstart/index.html @@ -32,7 +32,7 @@ Your system is all ready to go. <span class="o">[</span>INFO] <span class="o">[</span>App<span class="nv">$]</span> MyApp1 | 1 | 3mZWDzci2D5YsqAnqNnXH9SB6Rg3dsTBs8iHkK6X2i54IQsIZI1eEeQQyMfs7b3F | <span class="o">(</span>all<span class="o">)</span> <span class="o">[</span>INFO] <span class="o">[</span>App<span class="nv">$]</span> MyApp2 | 2 | io5lz6Eg4m3Xe4JZTBFE13GMAf1dhFl6ZteuJfrO84XpdOz9wRCrDU44EUaYuXq5 | <span class="o">(</span>all<span class="o">)</span> <span class="o">[</span>INFO] <span class="o">[</span>App<span class="nv">$]</span> Finished listing 2 app<span class="o">(</span>s<span class="o">)</span>. -</pre></td></tr></tbody></table> </div> <p><a href="#"></a></p> <h2 id='4.-collecting-data' class='header-anchors'>4. Collecting Data</h2><p>Next, let's collect training data for this Engine. By default, Complementary Purchase Engine Template supports the following entities: <strong>user</strong>, <strong>item</strong>. A user buys an item. This template requires user-buy-item events.</p><p>Note that the engine requires correct buy event time being used in order to determine if the items being bought are in the same 'basket', which is configured by the 'basketWindow' parameter. Using an unreal event time for the buy events will cause an incorrect model. If you use SDK, the current time is used as event time by default.</p><div class="alert-message warning"><p>In particular, make sure correct event time is specified if you import data in batch (i.e. not in real time). If the event time is omitted, the SDK will use <strong>current time</strong> as event time which is not the actual time of the buy event in this case!</p></div> <p>You can send these events to PredictionIO Event Server in real-time easily by making a HTTP request or through the provided SDK. Please see <a href="/appintegration/">App Integration Overview</a> for more details how to integrate your app with SDK.</p><p>Let's try sending events to EventServer with the following <code>curl</code> commands (The corresponding SDK code is showed in other tabs).</p><p>Replace <code><ACCCESS_KEY></code> by the Access Key generated in above steps. Note that <code>localhost:7070</code> is the default URL of the Event Server.</p><p>For convenience, set your access key to the shell variable, run:</p><p><code>$ ACCESS_KEY=<ACCESS_KEY></code></p> <p><a href="#"></a></p> <p>When an user u0 buys item i0 on time <code>2014-11-02T09:39:45.618-08:00</code> (current time will be used if eventTime is not specified), you can send a buy event. Run the following <code>curl</code> command: </p><div class="tabs"> <ul class="control"> <li data-lang="json"><a href="#tab-5fbbf61c-e20e-4acb-826d-d1487ef36bf1">REST API</a></li> <li data-lang="python"><a href="#tab-aac2be91-6c39-4fee-b507-206a4eb446d2">Python SDK</a></li> <li data-lang="php"><a href="#tab-37546e3a-9b13-4072-852f-4a053325547a">PHP SDK</a></li> <li data-lang="ruby"><a href="#tab-aaa32b91-010e-431d-8c87-3c018b7c58ca">Ruby SDK</a></li> <li data-lang="java"><a href="#tab-d81828d2-800b-488a-b36b-7e601e0ee905">Java SDK</a></li> </ul> <div data-tab="REST API" data-lang="json" id="tab-5fbbf61c-e20e-4acb-826d-d1487ef36bf1"> <div class="highlight shell"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td></tr></tbody></table> </div> <p><a href="#"></a></p> <h2 id='4.-collecting-data' class='header-anchors'>4. Collecting Data</h2><p>Next, let's collect training data for this Engine. By default, Complementary Purchase Engine Template supports the following entities: <strong>user</strong>, <strong>item</strong>. A user buys an item. This template requires user-buy-item events.</p><p>Note that the engine requires correct buy event time being used in order to determine if the items being bought are in the same 'basket', which is configured by the 'basketWindow' parameter. Using an unreal event time for the buy events will cause an incorrect model. If you use SDK, the current time is used as event time by default.</p><div class="alert-message warning"><p>In particular, make sure correct event time is specified if you import data in batch (i.e. not in real time). If the event time is omitted, the SDK will use <strong>current time</strong> as event time which is not the actual time of the buy event in this case!</p></div> <p>You can send these events to PredictionIO Event Server in real-time easily by making a HTTP request or through the provided SDK. Please see <a href="/appintegration/">App Integration Overview</a> for more details how to integrate your app with SDK.</p><p>Let's try sending events to EventServer with the following <code>curl</code> commands (The corresponding SDK code is showed in other tabs).</p><p>Replace <code><ACCCESS_KEY></code> by the Access Key generated in above steps. Note that <code>localhost:7070</code> is the default URL of the Event Server.</p><p>For convenience, set your access key to the shell variable, run:</p><p><code>$ ACCESS_KEY=<ACCESS_KEY></code></p> <p><a href="#"></a></p> <p>When an user u0 buys item i0 on time <code>2014-11-02T09:39:45.618-08:00</code> (current time will be used if eventTime is not specified), you can send a buy event. Run the following <code>curl</code> command: </p><div class="tabs"> <ul class="control"> <li data-lang="json"><a href="#tab-0815596f-087b-4528-bc33-d3b1af2d753b">REST API</a></li> <li data-lang="python"><a href="#tab-054e3ced-b183-423b-8030-8e1cf25b1a47">Python SDK</a></li> <li data-lang="php"><a href="#tab-cad9c87c-4bd5-420f-a1bd-99ab3121bbaf">PHP SDK</a></li> <li data-lang="ruby"><a href="#tab-c268db04-f815-42c9-a2b1-dc2ad0ffb9c3">Ruby SDK</a></li> <li data-lang="java"><a href="#tab-405d1652-00ea-42b7-81d3-e98a41560e5a">Java SDK</a></li> </ul> <div data-tab="REST API" data-lang="json" id="tab-0815596f-087b-4528-bc33-d3b1af2d753b"> <div class="highlight shell"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -51,7 +51,7 @@ Your system is all ready to go. "targetEntityId" : "i0", "eventTime" : "2014-11-02T09:39:45.618-08:00" }'</span> -</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Python SDK" data-lang="python" id="tab-aac2be91-6c39-4fee-b507-206a4eb446d2"> <div class="highlight python"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Python SDK" data-lang="python" id="tab-054e3ced-b183-423b-8030-8e1cf25b1a47"> <div class="highlight python"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -104,7 +104,7 @@ Your system is all ready to go. <span class="n">target_entity_id</span><span class="o">=<</span><span class="n">ITEM</span> <span class="n">ID</span><span class="o">></span><span class="p">,</span> <span class="n">event_time</span><span class="o">=<</span><span class="n">EVENT_TIME</span><span class="o">></span> <span class="p">)</span> -</pre></td> </tr></tbody></table> </div> </div> <div data-tab="PHP SDK" data-lang="php" id="tab-37546e3a-9b13-4072-852f-4a053325547a"> <div class="highlight php"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td> </tr></tbody></table> </div> </div> <div data-tab="PHP SDK" data-lang="php" id="tab-cad9c87c-4bd5-420f-a1bd-99ab3121bbaf"> <div class="highlight php"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -155,7 +155,7 @@ Your system is all ready to go. <span class="p">));</span> <span class="cp">?></span> -</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Ruby SDK" data-lang="ruby" id="tab-aaa32b91-010e-431d-8c87-3c018b7c58ca"> <div class="highlight ruby"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Ruby SDK" data-lang="ruby" id="tab-c268db04-f815-42c9-a2b1-dc2ad0ffb9c3"> <div class="highlight ruby"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -200,7 +200,7 @@ Your system is all ready to go. <span class="s1">'eventTime'</span> <span class="o">=></span> <span class="o"><</span><span class="no">EVENT_TIME</span><span class="o">></span> <span class="p">}</span> <span class="p">)</span> -</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Java SDK" data-lang="java" id="tab-d81828d2-800b-488a-b36b-7e601e0ee905"> <div class="highlight java"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Java SDK" data-lang="java" id="tab-405d1652-00ea-42b7-81d3-e98a41560e5a"> <div class="highlight java"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -250,7 +250,7 @@ Your system is all ready to go. <span class="o">.</span><span class="na">eventTime</span><span class="o">(<</span><span class="n">EVENT_TIME</span><span class="o">>)</span> <span class="n">client</span><span class="o">.</span><span class="na">createEvent</span><span class="o">(</span><span class="n">buyEvent</span><span class="o">);</span> </pre></td> </tr></tbody></table> </div> </div> </div> <p><h3 id='query-event-server' class='header-anchors'>Query Event Server</h3><p>Now let's query the EventServer and see if these events are imported successfully.</p><p>Go to following URL with your browser:</p><p><code><a href="http://localhost:7070/events.json?accessKey=&lt;YOUR_ACCESS_KEY";>http://localhost:7070/events.json?accessKey=&lt;YOUR_ACCESS_KEY</a>></code></p><p>or run the following command in terminal:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1</pre></td><td class="code"><pre><span class="gp">$ </span>curl -i -X GET <span class="s2">"<a href="http://localhost:7070/events.json?accessKey=";>http://localhost:7070/events.json?accessKey=</a></span><span class="nv">$ACCESS_KEY</span><span class="s2">"</span> -</pre></td></tr></tbody></table> </div> <div class="alert-message note"><p>Note that you should quote the entire URL by using single or double quotes when you run the <code>curl</code> command.</p></div><p>It should return the imported events in JSON format. You can refer to <a href="/datacollection/eventapi/#debugging-recipes">Event Server Debugging Recipes</a> for more different ways to query Event Server.</p></p><h3 id='import-more-sample-data' class='header-anchors'>Import More Sample Data</h3> <p>This engine requires more data in order to train a useful model. Instead of sending more events one by one in real time, for quickstart demonstration purpose, we are going to use a script to import more events in batch.</p> <p>A Python import script <code>import_eventserver.py</code> is provided to import sample data. The script generates some frequent item sets (prefix with "s"), some other random items (prefix with "i") and a few popular items (prefix with "p "). Then each user (with user ID "u1" to "u10") performs 5 buy transactions (buy events are within 10 seconds in each transcation). In each transcation, the user may or may not buy some random items, always buy one of the popular items and buy 2 or more items in one of the frequent item sets.</p> <p>First, you will need to install Python SDK in order to run the sample data import script. To install Python SDK, run:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1</pre></td><td class="code"><pre><span class="gp">$ </span>pip install predictionio +</pre></td></tr></tbody></table> </div> <div class="alert-message note"><p>Note that you should quote the entire URL by using single or double quotes when you run the <code>curl</code> command.</p></div><p>It should return the imported events in JSON format. You can refer to <a href="/datacollection/eventapi/#debugging-recipes">Event Server Debugging Recipes</a> for more different ways to query Event Server.</p></p><h3 id='import-more-sample-data' class='header-anchors'>Import More Sample Data</h3> <p>This engine requires more data in order to train a useful model. Instead of sending more events one by one in real time, for quickstart demonstration purpose, we are going to use a script to import more events in batch.</p> <p>A Python import script <code>import_eventserver.py</code> is provided to import sample data. The script generates some frequent item sets (prefix with "s"), some other random items (prefix with "i") and a few popular items (prefix with "p "). Then each user (with user ID "u1" to "u10") performs 5 buy transactions (buy events are within 10 seconds in each transaction). In each transaction, the user may or may not buy some random items, always buy one of the popular items and buy 2 or more items in one of the frequent item sets.</p> <p>First, you will need to install Python SDK in order to run the sample data import script. To install Python SDK, run:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1</pre></td><td class="code"><pre><span class="gp">$ </span>pip install predictionio </pre></td></tr></tbody></table> </div> <p>or</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1</pre></td><td class="code"><pre><span class="gp">$ </span>easy_install predictionio </pre></td></tr></tbody></table> </div> <div class="alert-message note"><p>You may need <code>sudo</code> access if you have permission issue. (ie. <code>sudo pip install predictionio</code>)</p></div> <p><a href="#"></a></p> <p>Make sure you are under the <code>MyComplementaryPurchase</code> directory. Execute the following to import the data:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 2</pre></td><td class="code"><pre><span class="gp">$ </span><span class="nb">cd </span>MyComplementaryPurchase @@ -290,7 +290,7 @@ User u10 buys item s2i1 at 2014-10-19 15:43:15.618000-07:53 </pre></td></tr></tbody></table> </div> <p>When the engine is deployed successfully and running, you should see a console message similar to the following:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 2</pre></td><td class="code"><pre><span class="o">[</span>INFO] <span class="o">[</span>HttpListener] Bound to /0.0.0.0:8000 <span class="o">[</span>INFO] <span class="o">[</span>MasterActor] Bind successful. Ready to serve. -</pre></td></tr></tbody></table> </div> <p>Do not kill the deployed engine process.</p><p>By default, the deployed engine binds to <a href="http://localhost:8000";><a href="http://localhost:8000";>http://localhost:8000</a></a>. You can visit that page in your web browser to check its status.</p><p><img alt="Engine Status" src="/images/engine-server-3246414b.png"/></p></p><h2 id='6.-use-the-engine' class='header-anchors'>6. Use the Engine</h2><p>Now, You can query the engine. For example, return top 3 items which are frequently bought with item "s2i1". You can sending this JSON '{ "items" : ["s2i1"], "num" : 3 }' to the deployed engine. The engine will return a JSON with the recommended items.</p><p>If you include one or more items in the query, the engine will use each combination of the query items as condition, and return recommended items if there is any for this condition. For example, if you query items are ["A", "B&q uot;], then the engine will use ["A"], ["B"], and ["A", "B"] as condition and try to find top n recommended items for each combination.</p><p>You can simply send a query by making a HTTP request or through the <code>EngineClient</code> of an SDK.</p><p>With the deployed engine running, open another terminal and run the following <code>curl</code> command or use SDK to send the query:</p><div class="tabs"> <ul class="control"> <li data-lang="json"><a href="#tab-57403196-e4cb-4b65-965a-640c9a4b64b8">REST API</a></li> <li data-lang="python"><a href="#tab-c2df4a5b-b4d4-4f5e-a6b1-4e8d6698fed7">Python SDK</a></li> <li data-lang="php"><a href="#tab-0f9425b4-e145-4491-a9bc-6bfba4b6f990">PHP SDK</a></li> <li data-lang="ruby"><a href="#tab-3b361289-52a1-4a8c-b5f4-09fa14327374">Ruby SDK</a></li> <li data-lang="java"><a href="#tab-6ad8485a-9e12-4d17-a2d8-71c095eaafb0">Java SDK</a></li> </ul> <div data-tab="REST API" data-lang="json" id="tab-57403196-e4cb- 4b65-965a-640c9a4b64b8"> <div class="highlight shell"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td></tr></tbody></table> </div> <p>Do not kill the deployed engine process.</p><p>By default, the deployed engine binds to <a href="http://localhost:8000";><a href="http://localhost:8000";>http://localhost:8000</a></a>. You can visit that page in your web browser to check its status.</p><p><img alt="Engine Status" src="/images/engine-server-3246414b.png"/></p></p><h2 id='6.-use-the-engine' class='header-anchors'>6. Use the Engine</h2><p>Now, You can query the engine. For example, return top 3 items which are frequently bought with item "s2i1". You can sending this JSON '{ "items" : ["s2i1"], "num" : 3 }' to the deployed engine. The engine will return a JSON with the recommended items.</p><p>If you include one or more items in the query, the engine will use each combination of the query items as condition, and return recommended items if there is any for this condition. For example, if you query items are ["A", "B&q uot;], then the engine will use ["A"], ["B"], and ["A", "B"] as condition and try to find top n recommended items for each combination.</p><p>You can simply send a query by making a HTTP request or through the <code>EngineClient</code> of an SDK.</p><p>With the deployed engine running, open another terminal and run the following <code>curl</code> command or use SDK to send the query:</p><div class="tabs"> <ul class="control"> <li data-lang="json"><a href="#tab-8c455c80-2f61-4e1c-89b1-f6024704d8cc">REST API</a></li> <li data-lang="python"><a href="#tab-60180116-078e-448f-af6a-74833ee6d5ec">Python SDK</a></li> <li data-lang="php"><a href="#tab-c59c455d-e7f1-4c00-bfb5-cff5cb852ba5">PHP SDK</a></li> <li data-lang="ruby"><a href="#tab-fb4182f1-4994-420e-a344-289089184e1e">Ruby SDK</a></li> <li data-lang="java"><a href="#tab-31c3b80c-9336-45ab-981d-466d9c759e93">Java SDK</a></li> </ul> <div data-tab="REST API" data-lang="json" id="tab-8c455c80-2f61- 4e1c-89b1-f6024704d8cc"> <div class="highlight shell"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -303,7 +303,7 @@ User u10 buys item s2i1 at 2014-10-19 15:43:15.618000-07:53 }'</span> <span class="se">\</span> http://localhost:8000/queries.json -</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Python SDK" data-lang="python" id="tab-c2df4a5b-b4d4-4f5e-a6b1-4e8d6698fed7"> <div class="highlight python"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Python SDK" data-lang="python" id="tab-60180116-078e-448f-af6a-74833ee6d5ec"> <div class="highlight python"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -314,7 +314,7 @@ http://localhost:8000/queries.json <span class="s">"items"</span> <span class="p">:</span> <span class="p">[</span><span class="s">"s2i1"</span><span class="p">],</span> <span class="s">"num"</span> <span class="p">:</span> <span class="mi">3</span> <span class="p">})</span> -</pre></td> </tr></tbody></table> </div> </div> <div data-tab="PHP SDK" data-lang="php" id="tab-0f9425b4-e145-4491-a9bc-6bfba4b6f990"> <div class="highlight php"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td> </tr></tbody></table> </div> </div> <div data-tab="PHP SDK" data-lang="php" id="tab-c59c455d-e7f1-4c00-bfb5-cff5cb852ba5"> <div class="highlight php"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -341,7 +341,7 @@ http://localhost:8000/queries.json <span class="nb">print_r</span><span class="p">(</span><span class="nv">$response</span><span class="p">);</span> <span class="cp">?></span> -</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Ruby SDK" data-lang="ruby" id="tab-3b361289-52a1-4a8c-b5f4-09fa14327374"> <div class="highlight ruby"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Ruby SDK" data-lang="ruby" id="tab-fb4182f1-4994-420e-a344-289089184e1e"> <div class="highlight ruby"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -360,7 +360,7 @@ http://localhost:8000/queries.json <span class="p">)</span> <span class="nb">puts</span> <span class="n">response</span> -</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Java SDK" data-lang="java" id="tab-6ad8485a-9e12-4d17-a2d8-71c095eaafb0"> <div class="highlight java"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td> </tr></tbody></table> </div> </div> <div data-tab="Java SDK" data-lang="java" id="tab-31c3b80c-9336-45ab-981d-466d9c759e93"> <div class="highlight java"> <table style="border-spacing: 0"><tbody><tr> <td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -389,7 +389,7 @@ http://localhost:8000/queries.json <span class="s">"items"</span><span class="o">,</span> <span class="n">ImmutableList</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"s2i1"</span><span class="o">),</span> <span class="s">"num"</span><span class="o">,</span> <span class="mi">3</span> <span class="o">));</span> -</pre></td> </tr></tbody></table> </div> </div> </div> <p>The following is sample JSON response. The <code>cond</code> field is one of the combination of query items used as condition to determine other frequently bought items with this condition, followed by top items. If there are multiple conditions with recommended items found, the <code>rules</code> array will contain mutliple elements, and each correspond to the condition.</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td> </tr></tbody></table> </div> </div> </div> <p>The following is sample JSON response. The <code>cond</code> field is one of the combination of query items used as condition to determine other frequently bought items with this condition, followed by top items. If there are multiple conditions with recommended items found, the <code>rules</code> array will contain multiple elements, and each correspond to the condition.</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4
http://git-wip-us.apache.org/repos/asf/predictionio-site/blob/9fe018b6/templates/ecommercerecommendation/dase/index.html ---------------------------------------------------------------------- diff --git a/templates/ecommercerecommendation/dase/index.html b/templates/ecommercerecommendation/dase/index.html index 8ab46e3..5fabb87 100644 --- a/templates/ecommercerecommendation/dase/index.html +++ b/templates/ecommercerecommendation/dase/index.html @@ -138,7 +138,7 @@ <span class="o">}</span>, ... <span class="o">}</span> -</pre></td></tr></tbody></table> </div> <p>In <code>readTraining()</code>, <code>PEventStore</code> is an object which provides function to access dataa that is collected by PredictionIO Event Server.</p><p>This E-Commerce Recommendation Engine Template requires "user" and "item" entities that are set by events.</p><p><code>PEventStore.aggregateProperties(...)</code> aggregates properties of the <code>user</code> and <code>item</code> that are set, unset, or delete by special events <strong>$set</strong>, <strong>$unset</strong> and <strong>$delete</strong>. Please refer to <a href="/datacollection/eventapi/#note-about-properties">Event API</a> for more details of using these events.</p><p>The following code aggregates the properties of <code>user</code> and then map each result to a <code>User()</code> object.</p><div class="highlight scala"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td></tr></tbody></table> </div> <p>In <code>readTraining()</code>, <code>PEventStore</code> is an object which provides function to access data that is collected by PredictionIO Event Server.</p><p>This E-Commerce Recommendation Engine Template requires "user" and "item" entities that are set by events.</p><p><code>PEventStore.aggregateProperties(...)</code> aggregates properties of the <code>user</code> and <code>item</code> that are set, unset, or delete by special events <strong>$set</strong>, <strong>$unset</strong> and <strong>$delete</strong>. Please refer to <a href="/datacollection/eventapi/#note-about-properties">Event API</a> for more details of using these events.</p><p>The following code aggregates the properties of <code>user</code> and then map each result to a <code>User()</code> object.</p><div class="highlight scala"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -361,7 +361,7 @@ <span class="n">lambda</span><span class="k">:</span> <span class="kt">Double</span><span class="o">,</span> <span class="n">seed</span><span class="k">:</span> <span class="kt">Option</span><span class="o">[</span><span class="kt">Long</span><span class="o">]</span> <span class="o">)</span> <span class="k">extends</span> <span class="nc">Params</span> -</pre></td></tr></tbody></table> </div> <p>Parameter description:</p> <ul> <li><strong>appName</strong>: Your App name. Events defined by "seenEvents" and "similarEvents" will be read from this app during <code>predict</code>.</li> <li><strong>unseenOnly</strong>: true or false. Set to true if you want to recommmend unseen items only. Seen items are defined by <em>seenEvents</em> which mean if the user has these events on the items, then it's treated as <em>seen</em>.</li> <li><strong>seenEvents</strong>: A list of user-to-item events which will be treated as <em>seen</em> events. Used when <em>unseenOnly</em> is set to true.</li> <li><strong>similarEvents</strong>: A list of user-item-item events which will be used to find similar items to the items which the user has performend these events on.</li> <li><strong>rank</strong>: Parameter of the MLlib ALS algorithm. Number of latent features.</li> <li><strong>numIterations</strong>: Parameter of the MLlib ALS algorithm. Number of iterations.</li> <li><strong>lambda</strong>: Regularization parameter of the MLlib ALS algorithm.</li> <li><strong>seed</strong>: Optional. A random seed of the MLlib ALS algorithm. Specify a fixed value if want to have deterministic result.</li> </ul> <h3 id='train(...)' class='header-anchors'>train(...)</h3><p><code>train</code> is called when you run <strong>pio train</strong>. This is where MLlib ALS algorithm, i.e. <code>ALS.trainImplicit()</code>, is used to train a predictive model. In addition, we also count the number of items being bought for each item as default model which will be used when there is no ALS model available or other useful information about the user is available during <code>predict</code>.</p><div class="highlight scala"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td></tr></tbody></table> </div> <p>Parameter description:</p> <ul> <li><strong>appName</strong>: Your App name. Events defined by "seenEvents" and "similarEvents" will be read from this app during <code>predict</code>.</li> <li><strong>unseenOnly</strong>: true or false. Set to true if you want to recommend unseen items only. Seen items are defined by <em>seenEvents</em> which mean if the user has these events on the items, then it's treated as <em>seen</em>.</li> <li><strong>seenEvents</strong>: A list of user-to-item events which will be treated as <em>seen</em> events. Used when <em>unseenOnly</em> is set to true.</li> <li><strong>similarEvents</strong>: A list of user-item-item events which will be used to find similar items to the items which the user has performed these events on.</li> <li><strong>rank</strong>: Parameter of the MLlib ALS algorithm. Number of latent features.</li> <li><strong>numIterations</strong>: Parameter of the MLlib ALS al gorithm. Number of iterations.</li> <li><strong>lambda</strong>: Regularization parameter of the MLlib ALS algorithm.</li> <li><strong>seed</strong>: Optional. A random seed of the MLlib ALS algorithm. Specify a fixed value if want to have deterministic result.</li> </ul> <h3 id='train(...)' class='header-anchors'>train(...)</h3><p><code>train</code> is called when you run <strong>pio train</strong>. This is where MLlib ALS algorithm, i.e. <code>ALS.trainImplicit()</code>, is used to train a predictive model. In addition, we also count the number of items being bought for each item as default model which will be used when there is no ALS model available or other useful information about the user is available during <code>predict</code>.</p><div class="highlight scala"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -513,7 +513,7 @@ <span class="n">mllibRatings</span> <span class="o">}</span> -</pre></td></tr></tbody></table> </div> <div class="alert-message note"><p>You can customize this function if you want to convert other events to MLlibRating or need different ways to aggreagte the events into MLlibRating.</p></div><p>In addition to <code>RDD[MLlibRating]</code>, <code>ALS.trainImplicit</code> takes the following parameters: <em>rank</em>, <em>iterations</em>, <em>lambda</em> and <em>seed</em>.</p><p>The values of these parameters are specified in <em>algorithms</em> of MyECommerceRecommendation/<strong><em>engine.json</em></strong>:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td></tr></tbody></table> </div> <div class="alert-message note"><p>You can customize this function if you want to convert other events to MLlibRating or need different ways to aggregate the events into MLlibRating.</p></div><p>In addition to <code>RDD[MLlibRating]</code>, <code>ALS.trainImplicit</code> takes the following parameters: <em>rank</em>, <em>iterations</em>, <em>lambda</em> and <em>seed</em>.</p><p>The values of these parameters are specified in <em>algorithms</em> of MyECommerceRecommendation/<strong><em>engine.json</em></strong>:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -550,7 +550,7 @@ <span class="o">]</span> ... <span class="o">}</span> -</pre></td></tr></tbody></table> </div> <p>The parameters <code>appName</code>, <code>unseenOnly</code>, <code>seenEvents</code> and <code>similarEvents</code> are used during <code>predict()</code>, which will be explained later.</p><p>PredictionIO will automatically loads these values into the constructor <code>ap</code>, which has a corresponding case class <code>ECommAlgorithmParams</code>.</p><p>The <code>seed</code> parameter is an optional parameter, which is used by MLlib ALS algorithm internally to generate random values. If the <code>seed</code> is not specified, current system time would be used and hence each train may produce different reuslts. Specify a fixed value for the <code>seed</code> if you want to have deterministic result (For example, when you are testing).</p><p><code>ALS.trainImplicit()</code> returns a <code>MatrixFactorizationModel</code> model which contains two RDDs: userFeatures and productFeatures. They correspond to the user X latent features matrix and item X latent features matrix, respectively.</p><p>In addition to the latent feature vector, the item properties (e.g. categories) and popular count are also used during <code>predict()</code>. Hence, we also save these data along with the feature vector by joining them and then collect the data as local Map. Each item is represented by a <code>ProductModel</code> class, which cosists of the <code>item</code> information, <code>features</code> calculated by ALS, and <code>count</code> returned by <code>trainDefault()</code>.</p><div class="highlight scala"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td></tr></tbody></table> </div> <p>The parameters <code>appName</code>, <code>unseenOnly</code>, <code>seenEvents</code> and <code>similarEvents</code> are used during <code>predict()</code>, which will be explained later.</p><p>PredictionIO will automatically loads these values into the constructor <code>ap</code>, which has a corresponding case class <code>ECommAlgorithmParams</code>.</p><p>The <code>seed</code> parameter is an optional parameter, which is used by MLlib ALS algorithm internally to generate random values. If the <code>seed</code> is not specified, current system time would be used and hence each train may produce different results. Specify a fixed value for the <code>seed</code> if you want to have deterministic result (For example, when you are testing).</p><p><code>ALS.trainImplicit()</code> returns a <code>MatrixFactorizationModel</code> model which contains two RDDs: userFeatures and productFeatures. They correspond to the user X latent features matrix and item X latent features matrix, respectively.</p><p>In addition to the latent feature vector, the item properties (e.g. categories) and popular count are also used during <code>predict()</code>. Hence, we also save these data along with the feature vector by joining them and then collect the data as local Map. Each item is represented by a <code>ProductModel</code> class, which consists of the <code>item</code> information, <code>features</code> calculated by ALS, and <code>count</code> returned by <code>trainDefault()</code>.</p><div class="highlight scala"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -625,7 +625,7 @@ <span class="k">val</span> <span class="n">userStringIntMap</span><span class="k">:</span> <span class="kt">BiMap</span><span class="o">[</span><span class="kt">String</span>, <span class="kt">Int</span><span class="o">],</span> <span class="k">val</span> <span class="n">itemStringIntMap</span><span class="k">:</span> <span class="kt">BiMap</span><span class="o">[</span><span class="kt">String</span>, <span class="kt">Int</span><span class="o">]</span> <span class="o">)</span> <span class="k">extends</span> <span class="nc">Serializable</span> <span class="o">{</span> <span class="o">...</span> <span class="o">}</span> -</pre></td></tr></tbody></table> </div> <p>PredictionIO will automatically store the returned model after training, i.e. <code>ECommModel</code> in this example.</p><h3 id='predict(...)' class='header-anchors'>predict(...)</h3><p><code>predict</code> is called when you send a JSON query to <a href="http://localhost:8000/queries.json";>http://localhost:8000/queries.json</a>. PredictionIO converts the query, such as <code>{ "user": "u1", "num": 4 }</code> to the <code>Query</code> class you defined previously.</p><p>We can use the userFeatures and productFeatures stored in ECommModel to calculate the scores of items for the user.</p><p>This template also supports additional business logic features, such as filtering items by categories, recommending items in the white list, excluding items in the black list, recommend unseen items only, and exclude unavaiable items defined in constraint event.</p><p>The <code>predict()</code> function does the following:</ p> <ol> <li>Convert the item in query's whilteList from string ID to integer index</li> <li>Get a list seen items by the user (defined by parmater <code>seenEvents</code>)</li> <li>Get the latest unavailableItems which is used to exclude unavailable items for all users</li> <li>Combine query's blackList, seenItems, and unavailableItems into a final black list of items to be excluded from recommendation.</li> <li>Get the user feature vector from the ECommModel.</li> <li>If there is feature vector for the user, recommend top N items based on the user feature and prodcut features.</li> <li>If there is no feature vector for the user, use the recent items acted by the user (defined by <code>similarEvents</code> parameter) to recommend similar items.</li> <li>If there is no recent <code>similarEvents</code> available for the user, popular items are then recommended (added in template version 0.4.0).</li> </ol> <p>Only items which satisfy the <code>isCandidate()</code> condition wi ll be recommended. By default, the item can be recommended if:</p> <ul> <li>it belongs to one of the categories defined in query.</li> <li>it is one of the white list items if white list is defined.</li> <li>it is not in the black list.</li> </ul> <div class="alert-message info"><p>You can easily modify <code>isCandidate()</code> checking or related logic if you have different requirements or condition to determine if an item is a candidate item to be recommended.</p></div><div class="highlight scala"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 +</pre></td></tr></tbody></table> </div> <p>PredictionIO will automatically store the returned model after training, i.e. <code>ECommModel</code> in this example.</p><h3 id='predict(...)' class='header-anchors'>predict(...)</h3><p><code>predict</code> is called when you send a JSON query to <a href="http://localhost:8000/queries.json";>http://localhost:8000/queries.json</a>. PredictionIO converts the query, such as <code>{ "user": "u1", "num": 4 }</code> to the <code>Query</code> class you defined previously.</p><p>We can use the userFeatures and productFeatures stored in ECommModel to calculate the scores of items for the user.</p><p>This template also supports additional business logic features, such as filtering items by categories, recommending items in the white list, excluding items in the black list, recommend unseen items only, and exclude unavailable items defined in constraint event.</p><p>The <code>predict()</code> function does the following:< /p> <ol> <li>Convert the item in query's whiteList from string ID to integer index</li> <li>Get a list seen items by the user (defined by parameter <code>seenEvents</code>)</li> <li>Get the latest unavailableItems which is used to exclude unavailable items for all users</li> <li>Combine query's blackList, seenItems, and unavailableItems into a final black list of items to be excluded from recommendation.</li> <li>Get the user feature vector from the ECommModel.</li> <li>If there is feature vector for the user, recommend top N items based on the user feature and product features.</li> <li>If there is no feature vector for the user, use the recent items acted by the user (defined by <code>similarEvents</code> parameter) to recommend similar items.</li> <li>If there is no recent <code>similarEvents</code> available for the user, popular items are then recommended (added in template version 0.4.0).</li> </ol> <p>Only items which satisfy the <code>isCandidate()</code> condition w ill be recommended. By default, the item can be recommended if:</p> <ul> <li>it belongs to one of the categories defined in query.</li> <li>it is one of the white list items if white list is defined.</li> <li>it is not in the black list.</li> </ul> <div class="alert-message info"><p>You can easily modify <code>isCandidate()</code> checking or related logic if you have different requirements or condition to determine if an item is a candidate item to be recommended.</p></div><div class="highlight scala"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1 2 3 4 @@ -707,7 +707,7 @@ <span class="c1">// generate final blackList based on additional constraints </span> <span class="k">val</span> <span class="n">finalBlackList</span><span class="k">:</span> <span class="kt">Set</span><span class="o">[</span><span class="kt">Int</span><span class="o">]</span> <span class="k">=</span> <span class="n">genBlackList</span><span class="o">(</span><span class="n">query</span> <span class="k">=</span> <span class="n">query</span><span class="o">)</span> - <span class="c1">// convert seen Items list from String ID to interger Index + <span class="c1">// convert seen Items list from String ID to integer Index </span> <span class="o">.</span><span class="n">flatMap</span><span class="o">(</span><span class="n">x</span> <span class="k">=></span> <span class="n">model</span><span class="o">.</span><span class="n">itemStringIntMap</span><span class="o">.</span><span class="n">get</span><span class="o">(</span><span class="n">x</span><span class="o">))</span> <span class="c1">// look up user feature from model
